Coding style

Discussions related to programming Transport Empire.

Moderator: Transport Empire Moderators

Post Reply
User avatar
XeryusTC
Tycoon
Tycoon
Posts: 15415
Joined: 02 May 2005 11:05
Skype: XeryusTC
Location: localhost

Coding style

Post by XeryusTC » 10 Nov 2006 22:36

As we'll soon have an svn server, I decided to start a discussion about the coding style. I started the discussion on IRC:
#TransportEmpire wrote: <XeryusTC> azzaz, maybe we could write a coding style
<azzaz> thats not a bad idea
<XeryusTC> http://xeryustc.cjb.net/doxygen/style.html
<azzaz> i agree with that style, similar to mine
So this will be our new coding style. This style is quite usefull as it is the same as TRoS, which is also a major part of Transport Empire, making it A LOT easier for us developers to maintain both codes.
Don't panic - My YouTube channel - Follow me on twitter (@XeryusTC) - Play Tribes: Ascend - Tired of Dropbox? Try SpiderOak (use this link and we both get 1GB extra space)
Image
OpenTTD: manual #openttdcoop: blog | wiki | public server | NewGRF pack | DevZone
Image Image Image Image Image Image Image

User avatar
DominionSpy
Tycoon
Tycoon
Posts: 1429
Joined: 03 Oct 2003 23:59
Location: Lancashire, UK
Contact:

Post by DominionSpy » 11 Nov 2006 12:20

That style looks well thought out, simple and readable.
I would agree that it's good to have the same coding style as TRoS.

A lot of the previous coding style discussion was unnecessary because most people develop using IDEs which do most of the code management any way, and most of the suggestions were only useful if you only use a text editor to write the code.

I think we also need a common commenting style (beyond what is mentioned in yours), such as the information and layout in file header sections and method descriptions etc.
Image
You're saying I'm a Dominion spy, and don't even know it! - Dr. Bashir
That's the Joker in my avatar, not me. No wait it is me.

User avatar
XeryusTC
Tycoon
Tycoon
Posts: 15415
Joined: 02 May 2005 11:05
Skype: XeryusTC
Location: localhost

Post by XeryusTC » 11 Nov 2006 13:47

DominionSpy wrote:I think we also need a common commenting style (beyond what is mentioned in yours), such as the information and layout in file header sections and method descriptions etc.
Our comment style is pretty complicated if I would just explain it in total, but I'll only focus on doxygen files (header files):
We have a block in the beginning of the file (before the double include prevention macro) which marks that the file has to be parsed by doxygen, gives the autor and a small description, so something like this:

Code: Select all

/*! This is an example comment
    \author XeryusTC
    \file
*/
Then we have the comments for classes, which are basicly the same af for the file, but they don't include \file[\i] but can include loads of other things, an example:

Code: Select all

/*! This is an class that is just for proposing an comment style
    \author XeryusTC
    \brief Example class
    \warning This class doesn't do a thing
*/
class CExample { };
Then we have function comments, which can look like:

Code: Select all

const char Foo(int bar); //!< This function does some stuff \arg bar The int that we want to fiddle around with \returns The result of the algoritm
Or we can have the more readable and now more often used form (same function):

Code: Select all

/*! This function does some stuff
    \arg bar The int that we want to fiddle around with
    \returns The result of the algoritm
*/
const char Foo(int bar); 
This is basicly the method TRoS uses for documenting in the header files, I can give a explenation of the cpp files too, but those have a quite complecated structure with some exceptions, and it is also explained on the style page.
Don't panic - My YouTube channel - Follow me on twitter (@XeryusTC) - Play Tribes: Ascend - Tired of Dropbox? Try SpiderOak (use this link and we both get 1GB extra space)
Image
OpenTTD: manual #openttdcoop: blog | wiki | public server | NewGRF pack | DevZone
Image Image Image Image Image Image Image

User avatar
aarona
Traffic Manager
Traffic Manager
Posts: 221
Joined: 26 May 2006 15:54
Location: Perth, Australia
Contact:

Post by aarona » 25 Nov 2006 03:26

From my experience, its not just the code which should conform to some sort of standard. The project set up should be bound by some rules too. (Why oh why programmers can't just code and be done with is beyond me...)

I put these rules forward as a suggestion. (IMHO, there is nothing that incredible here)

1. The GCC compiler will be the de facto standard.
2. To compile the game, simply compile all files in the "TE/src/" directory, including all sub-directories.
3. All headers should be in their equivalent "TE/include/" directory.
Example:

Code: Select all

"TE/src/core/IVehicle.cpp" Line 1: #include "core/IVehicle.h"
"TE/include/core/IVehicle.h" Line 1: #ifndef __IVEHICLE_H__
4. There should be only ONE pre-compiler #define needed and that is _DEBUG. (Called by #ifdef _DEBUG)
(What I mean is that #define _DEBUG isn't part of the code, but part of the compiler options to be sent to gcc)

Dependencies
1. All dependencies should be compiled into their respective ".a" library files (in the TE/lib directory) If DLL's are required (although not desireable), they will also be automatically available (in the TE/bin directory).
2. The dependencies can be found (to be compiled if one wishes) in the TE/ext directory.
3. The headers of the dependencies should be installed into the compilers include directory. They can be found in the TE/ext/include/ directory and should all be copied into the $COMPILER/include directory.
Example:

Code: Select all

#include <XLib/XLib.h>
If you are using MinGW:
The file XLib.h will be available at C:/MinGW/include/XLib/XLib.h, etc
It will have originally have come from TE/ext/include/XLib/XLib.h
Other Compilers
1. Should someone decide to support a different compiler, they should place compiler specific files into a subdirectory
Examples: (Using MS Visual Studio)

Code: Select all

TE/lib/MSVS/
TE/bin/MSVS/
IDE Support
1. No specific IDE should be standard. Not even Makefiles!
2. IDE specific project files (with the exception of Makefiles, which are allowed to be in their native directory format) should be in sub directories.
Examples: (Using Code::Blocks)

Code: Select all

TE/build/CodeBlocks/
Anything else?

DaleStan
TTDPatch Developer
TTDPatch Developer
Posts: 10285
Joined: 18 Feb 2004 03:06
Contact:

Post by DaleStan » 25 Nov 2006 04:53

aarona wrote:1. The GCC compiler will be the de facto standard.
NAK. Support as many compilers as possible, and as fully as possible. This increases the chances of writing standards-compliant code, and thus decreases the work required to port to new compilers/platforms.
aarona wrote:3. All headers should be in their equivalent "TE/include/" directory.
NAK. "inc/". (This also applies to Dependencies #3)
aarona wrote:4. There should be only ONE pre-compiler #define needed and that is _DEBUG.
NAK. Cygwin apparently does not provide a functional libpng; it must be possible to remove the PNG code (if any) if Cygwin is to be a supported environment (see #5). Other users may want to configure without the ability to, for example, host network games.
Also:
A) Some well known compilers (such as GCC) provide extensions. These must be #ifdef-ed out under other compilers. (One such extension marks functions as "behaves like *printf", and enables the associated format/argument mismatch warnings.) The other option, failing to use these extensions despite the fact that they often catch errors is stupid, probably terminally so.
B) Some platforms (such as Windows) provide non-standard signatures for some functions. (mkdir comes to mind. POSIX specifies two arguments. Windows specifies one.) A macro may be used to ensure the correct number of arguments are specified, but behind the macro must lie some #ifdef that determines the POSIX-compliance of the platform.

5. Supported environments? Which shell(s), if any, is/are required? What OSen are supported?
aarona wrote:2. IDE specific project files (with the exception of Makefiles, which are allowed to be in their native directory format) should be in sub directories.
Partial ACK. Makefiles can quite easily be placed wherever you please. Why do they get special status, unless they are, in fact, the de facto standard?

All items not mentioned receive an ACK.
To get a good answer, ask a Smart Question. Similarly, if you want a bug fixed, write a Useful Bug Report. No TTDPatch crashlog? Then follow directions.
Projects: NFORenum (download) | PlaneSet (Website) | grfcodec (download) | grfdebug.log parser

User avatar
aarona
Traffic Manager
Traffic Manager
Posts: 221
Joined: 26 May 2006 15:54
Location: Perth, Australia
Contact:

Post by aarona » 25 Nov 2006 06:30

DaleStan wrote:NAK. Support as many compilers as possible, and as fully as possible. This increases the chances of writing standards-compliant code, and thus decreases the work required to port to new compilers/platforms.
Well yes, this goes without saying. The best thing to do is avoid situations which are "compiler" dependant or fob it off to someone (or something) else to deal with.
DaleStan wrote:NAK. "inc/". (This also applies to Dependencies #3)
<rant>You should stick with facts, not opinions because this is just pedantic. MinGW uses include, TRoS (the TE gfx engine) uses include. Not every friggin directory needs to be three letters.</rant>Sorry...
DaleStan wrote:NAK. Cygwin apparently does not provide a functional libpng; it must be possible to remove the PNG code (if any) if Cygwin is to be a supported environment (see #5). Other users may want to configure without the ability to, for example, host network games.
So what is the alternative to supporting PNG? If there isn't anything other than libpng, then what? Not support PNG? Sounds like Cygwin's problem, not ours...

I probably wasnt 100% clear about the config stuff but I have no objection to using the defines to remove things. My objection is using them just to get the friggin thing to compile.
DaleStan wrote:B) Some platforms (such as Windows) provide non-standard signatures for some functions. (mkdir comes to mind. POSIX specifies two arguments. Windows specifies one.) A macro may be used to ensure the correct number of arguments are specified, but behind the macro must lie some #ifdef that determines the POSIX-compliance of the platform.
I thought the environment you are in is automatically defined? If not then yes you have a point. In either case the intention is to use libraries which have already sorted all this crap out.
DaleStan wrote:5. Supported environments? Which shell(s), if any, is/are required? What OSen are supported?
We intended on making it as cross compatible as possible but let me say this...<rant>Windows is first, (Mac's second) no matter you linux people think. 90% of the user base will be probably be windows people. If some moron wants it to work on their toaster then they can do it themselves.</rant>
DaleStan wrote:Partial ACK. Makefiles can quite easily be placed wherever you please. Why do they get special status, unless they are, in fact, the de facto standard?
99.99% of projects I have seen are littered with Makefiles, I don't see why this one was going to be any different. But hey, if they can be put in one spot then we should do that.

All items not mentioned receive an ACK.[/quote]Thanks for your input. No doubt I'm coming across as harsh as I've had nightmares in the past over things that just wont compile. I have a 30 minute rule that if I can't get something to compile in 30 minutes I don't bother. I'm sure some people are even less forgiving. Its no wonder people turn to Java...

User avatar
XeryusTC
Tycoon
Tycoon
Posts: 15415
Joined: 02 May 2005 11:05
Skype: XeryusTC
Location: localhost

Post by XeryusTC » 25 Nov 2006 21:49

You can keep the Makefile in one place, but it would become very big and (probably messy). I think that Makefiles in every directory are better. And another point about Makefiles, we need someone to addapt the TRoS Makefiles, as I have quite a little understanding of them (I know they use some Makefile.gen which specifies a bunch of stuff).

I also agree with the use of include/ as that is what TRoS uses and what the current SVN repo has.
Don't panic - My YouTube channel - Follow me on twitter (@XeryusTC) - Play Tribes: Ascend - Tired of Dropbox? Try SpiderOak (use this link and we both get 1GB extra space)
Image
OpenTTD: manual #openttdcoop: blog | wiki | public server | NewGRF pack | DevZone
Image Image Image Image Image Image Image

DaleStan
TTDPatch Developer
TTDPatch Developer
Posts: 10285
Joined: 18 Feb 2004 03:06
Contact:

Post by DaleStan » 26 Nov 2006 04:21

aarona wrote:
DaleStan wrote:NAK. "inc/". (This also applies to Dependencies #3)
<rant>You should stick with facts, not opinions because this is just pedantic. MinGW uses include, TRoS (the TE gfx engine) uses include. Not every friggin directory needs to be three letters.</rant>Sorry...
Actually, now that I think about it some more, headers should generally go in the same directory as the files that #include them. They are, after all, part of the source.
The one major exception to this rule is found in Patch's directory structure. The assembly code is split (for good reason) into two directories: patches/ and procs/. When files from both directories need the same header, it can be found in inc/. However, when the header is specific to files in patches/, the include will also be found in patches/, not in inc/.
The general rule, IMO, is "Use ./ whenever possible. If that is not possible, use $PROJECT_ROOT/inc/." There are, of course, exceptions: Patch's inc/imports/ and Open's tables/ directories come immediately to mind.
It's a hassle to have to type '#include "../include/file.h"' instead of '#include "file.h"'. Obviously, if the project config/Makefile/&c. is such that ../include/ is in the header search path, this becomes a non-issue.
aarona wrote:I probably wasnt 100% clear about the config stuff but I have no objection to using the defines to remove things. My objection is using them just to get the friggin thing to compile.
Of course. Assuming the presence of a competent shell, typing "./configure && make" (or, if the project is set up this way, just "make") should either give you a sane error message, such as "no compiler found, aborting", or a binary. Having to read READMEs or futz around for make onlythebinaryanddonotinstallit is suboptimal.
aarona wrote:
DaleStan wrote:B) Some platforms (such as Windows) provide non-standard signatures for some functions. (mkdir comes to mind. POSIX specifies two arguments. Windows specifies one.) A macro may be used to ensure the correct number of arguments are specified, but behind the macro must lie some #ifdef that determines the POSIX-compliance of the platform.
I thought the environment you are in is automatically defined?
IIRC, the #definition of _WIN32, under Cygwin, is not sufficient to determine which of the following two lines will compile: (Exactly one will compile, but which one depends on the presence or absence of -m[no-]cygwin)
mkdir("temp"); // link directly to win32 libraires and dlls
mkdir("temp", 0755); // POSIX environments, including linking to cygwin1.dll
aarona wrote:In either case the intention is to use libraries which have already sorted all this crap out.
I believe boost::filesystem does this. I wrote NFORenum's directory-handling-code long before I discovered Boost, and have no intention of rewriting something that works just to take advantage of a library I don't need.
aarona wrote:
DaleStan wrote:Partial ACK. Makefiles can quite easily be placed wherever you please. Why do they get special status, unless they are, in fact, the de facto standard?
99.99% of projects I have seen are littered with Makefiles, I don't see why this one was going to be any different. But hey, if they can be put in one spot then we should do that.
They can be put in one spot, but this is rare. As XeryusTC points out, this causes them to be huge. The more pressing problem is that "make" may not do the expected thing if $PROJECT_ROOT does not contain a Makefile. I might consider changing this so that all build scripts and project files, for all IDEs, go in $PROJECT_ROOT. This causes a few minor problems with MSVS 7.1 vs MSVS 8.0, which use subtly different formats for their files, but still want to call them by the same names, but forcing a different name is an easy, one-time, procedure.
To get a good answer, ask a Smart Question. Similarly, if you want a bug fixed, write a Useful Bug Report. No TTDPatch crashlog? Then follow directions.
Projects: NFORenum (download) | PlaneSet (Website) | grfcodec (download) | grfdebug.log parser

Post Reply

Return to “Transport Empire Coding”

Who is online

Users browsing this forum: No registered users and 1 guest