Coding standard

[uzurpator]

http://tt2.sourceforge.net/wiki/index.p ... g_Standard

Any comments - do so in this thread

[DominionSpy]

This is what I said at the last meeting:

=== 2d. Coding - Evaluate and accept the coding standard ===
DominionSpy suggests that interfaces should have a prefixed I and classes a prefixed C, to avoid confusion between class names and method names. m and g prefixes should be followed by an underscore to help clarify things.

Just so that it's kept in people's minds.

[Hyronymus]

Small note: updating it is the responsibility of the coding group now, uploading the edited version to the website can be done by Steve (prefered) or me.

[Mek]

First of all, i wonder why someone just copied some random c++ coding standard without any justification why this is a good standard for this project...

Secondly i'm a big opponent of all the hungarion notation prefix stuff. The most used argument why it is good is it'll make code easier to read if you don't know the code, but i think this is absolutely not true as you'll first have to learn lots of useless abreviations that mean nothing before you can start to understand anything of the code...

If it were up to me, we'd just trash the current coding standard, and write our own one from scratch, and hopefully get something we are all happy with. Perhaps i'm completely alone with this point of view, and if that is the case i'll of course comply with whatever everybody else thinks is good, but for now, i haven't heard any reason why this is a good/appropriate coding standard.

[Hyronymus]

It was ChrisCF who pulled it of the net, I already deleted the crap intro to it. That doesn't mean you shouldn't consider ditching it all along if there's really no ground for sticking with the current one.

[Mek]

It was ChrisCF who pulled it of the net, I already deleted the crap intro to it. That doesn't mean you shouldn't consider ditching it all along if there's really no ground for sticking with the current one.

i'll try to write down what i would consider an ideal coding standard and post it here hopefully in the next couple of days...

[uzurpator]

Well - I personally don't care about the naming conventions. However - I really think that all variables should be explained in detail whn they are defined. Type might not be stated in the variable name - but its function should.

Besides - what should we call structures? Or pointers to structure of tables of object pointers or similar constructs?

When it comes to naming - I think we should stick to one convention across the board - say all iterator variables should be named

Code: Select all

type __name

or

Code: Select all

type iterName

or similar - so these would be easy to spot.

In another example if we have a table containing vertexes - the table should be named

Code: Select all

vertexSomethingSomethingElse

Also - each and every class should have its own namespace so it would be easy to spot which class certain variables belong to.

Other stuff can be handled by extensive commenting (And I mean extensive - each damn loop should have a description, each algorithm should get a detailed description). Petty discussions about class or method naming are imho irrelevant.

[Hellfire]

Other stuff can be handled by extensive commenting (And I mean extensive - each damn loop should have a description, each algorithm should get a detailed description). Petty discussions about class or method naming are imho irrelevant.

That is a very good point.

Also, each and every method and member variable of a class should have a description. Methods should also explain what their parameters "do"

[fujitsu]

Other stuff can be handled by extensive commenting (And I mean extensive - each damn loop should have a description, each algorithm should get a detailed description). Petty discussions about class or method naming are imho irrelevant.

That is a very good point.

Also, each and every method and member variable of a class should have a description. Methods should also explain what their parameters "do"

Yes! There should be no room for misunderstanding about what a function does/takes. It must be heavily commented, every parameter must be documented as to what it should actually contain, what it is used for...

I often use the m_ etc. prefixes in my code, and the do make things much easier to read.

William.

[uzurpator]

Then maybe we should - instead of making a stiff coding standard (altho SOME standard will have to be introduced) use a simple peer review?

Simply once I finish, say, Generator.cpp and Generator.h i give it to one of the other coders to review - once they understand what it does - it gets accepted.

[fujitsu]

Then maybe we should - instead of making a stiff coding standard (altho SOME standard will have to be introduced) use a simple peer review?

Simply once I finish, say, Generator.cpp and Generator.h i give it to one of the other coders to review - once they understand what it does - it gets accepted.

Peer review is a good way to ensure the readability of the code. We want everybody to be able to read/understand/etc. the code, so if only the person who wrote it can read it, it is useless. We have to have some peer review in there, although we still do need a fairly rigid standard.

William.

[Hyronymus]

Just make sure that the feedback about things that aren't accepted by peers is crystal clear and please avoid fighting over it.

[uzurpator]

Transport Empire Coding Standard

1. Source naming and distribution
2. Class requirements
3. Method requirements
4. Commenting

--

1.

Source files pending inclusion to the project must obey following rules:

Only .h, .cpp and .txt files are allowed

.h - is for defining classes and structures
.cpp - is for implementation of methods
.txt - is a description of a class.

The rule is - each method has its own source file.

Naming goes as follows:

class definition is always
TEclass.h

method implementations are
TEclass_methodx.cpp

constructor and destructor of a class are in
TEclass.cpp

method parameter structures are in
TEclass_methodx.cpp

Ferinstance we have a class 'F00BAR' with methods 'dostuff1', 'domorestuff', 'dorestofthestuff'
The files for these would look like this

TEF00BAR.h //definition of the class
TEF00BAR.cpp //constructor(s) and destructor

TEF00BAR_dostuff1.h
TEF00BAR_dostuff1.cpp

TEF00BAR_domorestuff.h
TEF00BAR_domorestuff.cpp

TEF00BAR_dorestofthestuff.h
TEF00BAR_dorestofthestuff.cpp

Note - each class has its own place in the class tree - and this place is
represented by the fact that the sources will be placed in a directory named
the same as the class inside. The directory tree will mimic the class diagram.

2.

A class has to have the following static fields:

char[x] Name = 'classname'; // a field containing the name of the class (eg Terrain)
char[5] Abbreviation = 'class name short; // a field containing 4 letter abbreviation of the class (eg Tern)
long int Count; // a field contaning information how many instances of the class are there currently;
long int Version; // unix time stamp of the date the file was uploaded
char Status; // status of the class: accepted, beta, alpha, final etc.

class field names are built in this manner

prefix_Varname_suffix

prefix and suffix are up to the coder.
Varname is a string that should describe as a noun with adjectives
(two at most) and a qualification what the variable is:

Structure - Ste
Pointer to structure - Stp
Double Pointer to structure - Std
Reference to structure - Str
Variable - Vae
Pointer to variable - Vap
Double Pointer to variable - Vad
Reference to variable - Var
Table - Tab
Object - Obe
Pointer to an object - Obp
Double pointer to an object - Obd
Refernce to an object - Obr
Other - Oth

For example:

pgegd_TrackElementsOnTileVar_pps - is a variable with two affixes, named
TrackElementsOnTile - and is a single variable (integer or somesuch)
TrackBendsTabVar - a table of variables (a table of ints, chars whatever)
TerrainTabObp_first - an affixed object pointer table

3. Method requirements

Methods always get their parameters through the parameter class (defined in
TEclass_func.h) or void. Even more - they must always do so with a pointer to an object.

Methods always return a pointer to an object or union(also defined in
TEclass_func.h) or void - called result class.

Methods may in special cases use a pointer to a table as a parameter - but
only in a case when there is only one parameter. Otherwise a structure must
be used.

The parameter/result class has all fields as public and may contain parameterless
constructor(s)/destructor or parameterless methods - altho it is advisible that the
parameter/result object was basicly a structure (ie - no methods and default
constructor/destructor)

The parameter/result class is always named

parMethodName
resMethodName

eg we have a method called DoStuff should be declared

resDoStuff *DoStuff(parDoStuff *par);

The parameter/result class must have static field called

int Version;

If the game is in Developer Mode before each call to a method the class the method
was called from should check if the version the class is compatible with the version
of the parameter/result classes in the current version of the parameter/result.

No class can call for methods of a class higher of the hierarchy tree.

4. Commenting

- Each source file starts with a table that shows:
Timestamp of the file
Author
And a neat TE ascii art logo

- before each method declaration the following data should be included:
what the method does
how the method does it
why this way of doing things was chosen

before each class field a description of what it is needed for must be provided
(what it is used for, is it private, and if so why etc)

before each loop a description must be provided what happens - how does it happen and why

note:

Code: Select all

for (int x=0;x<100;x++)
  for (int y=0;y<100;y++)
    {
    }

is considered a single loop, but

Code: Select all

for (int x=0;x<100;x++)
  {
  cout << "lol\n";
  for (int y=0;y<100;y++)
    {
    }
  }

is considered two seperate loops

Before ach condition a description must be provided what is being decided

note: the same rules as for loops apply

--

comments? additions?

I edited your post (added

Code: Select all

 tags) to emphasize the indentation rules you suggest. ~Hellfire @ 2005-10-10 1507 GMT[/color]

[Grunt]

The rule is - each method has its own source file.

Naming goes as follows:

class definition is always
TEclass.h

method implementations are
TEclass_methodx.cpp

constructor and destructor of a class are in
TEclass.cpp

method parameter structures are in
TEclass_methodx.cpp

Ferinstance we have a class 'F00BAR' with methods 'dostuff1', 'domorestuff', 'dorestofthestuff'
The files for these would look like this

TEF00BAR.h //definition of the class
TEF00BAR.cpp //constructor(s) and destructor

TEF00BAR_dostuff1.h
TEF00BAR_dostuff1.cpp

TEF00BAR_domorestuff.h
TEF00BAR_domorestuff.cpp

TEF00BAR_dorestofthestuff.h
TEF00BAR_dorestofthestuff.cpp

Note - each class has its own place in the class tree - and this place is
represented by the fact that the sources will be placed in a directory
named the same as the class inside. The directory tree will mimic the class
diagram.

Is it just me, or does this not create a needlessly large amount of file clutter? Why would we not use one-class-per-file as has been the standard with every other C++ project I have worked with? That would be just as organised, and would significantly cut back on file clutter.

[uzurpator]

not quite - each class will have its own directory where its sources will be kept.

And having each method in a seperate file will make it easier to navigate - otherwise the sources will get needlessly long, and I really hate when i have to scroll several screens to search for something.

Also - it will speed up compilation - since only relatively small sources will be compiled.

EDIT: and I don't need to know where you have put your methods.

Altho I can think of an exception here - if you use INLINE methods that are used just by one method then they can be defined in the same file as the method that calls them.

You know - if you have some mundane piece of code used in 20 places it is better to have an inline instead of calling for the method. Also - inlines would be always private and could would not use structures for parameters and results.

[DominionSpy]

I don't think this affects the final exe size.
It's an interesting concept that I've not seen before, but as you say it certainly could make our lives a little easier.

I'm not sure about the separate header files for each method though. I think it would be more useful to have a single header file for each class. The separate ones would only have one line in and a single one could also act as an index for reference.

[fujitsu]

I don't think this affects the final exe size.
It's an interesting concept that I've not seen before, but as you say it certainly could make our lives a little easier.

I'm not sure about the separate header files for each method though. I think it would be more useful to have a single header file for each class. The separate ones would only have one line in and a single one could also act as an index for reference.

It would make things easier, yes. I have never seen it used anywhere else before, but in something like this is seems like a Good Idea(tm). However, the header _should_ be a single file, as most of them are simply going to be one liners. It would be stupid to have a seperate header for each, and would make working out what is in each class incredibly difficult.

Do we really want to have to open up a million-zillion files to work out how to use various functions in a class? It is OK for the implementation files, because they will likely only be looked at one at a time. However you shouldn't need to look at the implementation to know what it does, because the documentation should be there in the header as a comment. Having them all in the one header means that you only have to open one per class, instead of one for each method, when you will almost definitely be using a number of functions from just a couple of classes. Are there any reasons for each method having its own header? I thought not.

William.

[uzurpator]

There is a reason for a header file for each method.

If person A wants to do work on class.method A and person B wants to work on class.method B - then with seperate files they just take the source and the header and once they finish - just upload new versions, while with a grouped headers the main file needs to be updated by hand on each new submission. Likewise with methods.

the main class header will simply include all method headers, so externally it will work just like the headers were in a single file.

[Grunt]

not quite - each class will have its own directory where its sources will be kept.

..which makes for one more directory level you have to traverse when looking for the source file you need to work with.

And having each method in a seperate file will make it easier to navigate - otherwise the sources will get needlessly long, and I really hate when i have to scroll several screens to search for something.

Most text editors have find features for exactly this reason.

Also - it will speed up compilation - since only relatively small sources will be compiled.

..however, there will be code repeated throughout every source file (thinking of header files, primarily); then there is a lot more code (from the perspective of the compiler) to work through, so this approach would result in longer compilation times, no? EDIT: in either case, you have the same amount of method code to compile, and whether or not that code is broken down into individual files or lumped together in one big file will itself make no difference in compilation time.

EDIT: and I don't need to know where you have put your methods.

...in the file of the associated class, of course.

Altho I can think of an exception here - if you use INLINE methods that are used just by one method then they can be defined in the same file as the method that calls them.

You know - if you have some mundane piece of code used in 20 places it is better to have an inline instead of calling for the method. Also - inlines would be always private and could would not use structures for parameters and results.

I agree with this - use inline methods wherever possible (i.e. under these circumstances) and our code efficiency will jump.

There is a reason for a header file for each method.

If person A wants to do work on class.method A and person B wants to work on class.method B - then with seperate files they just take the source and the header and once they finish - just upload new versions, while with a grouped headers the main file needs to be updated by hand on each new submission. Likewise with methods.

Untrue - any recent version control software (CVS, SVN) will merge changes as described above if they are made at the same time to the same file assuming the two changes are not diametrically opposed, which, by the description of editing two different methods, is not going to happen in the circumstances you describe.

[fujitsu]

There is a reason for a header file for each method.

If person A wants to do work on class.method A and person B wants to work on class.method B - then with seperate files they just take the source and the header and once they finish - just upload new versions, while with a grouped headers the main file needs to be updated by hand on each new submission. Likewise with methods.

Untrue - any recent version control software (CVS, SVN) will merge changes as described above if they are made at the same time to the same file assuming the two changes are not diametrically opposed, which, by the description of editing two different methods, is not going to happen in the circumstances you describe.

Speaking of CVS, Subversion, etc., I really think we should use Subversion, as it is so much more flexible, and was designed to be an improved CVS, and that it has been. I only used CVS here for a few weeks, then I gave up on it and moved to Subversion. There is no reason not to use Subversion, as large projects (such as Apache) now use SVN. OpenTTD uses SVN, and I don't believe they have problems with it.

All modern source-control systems invalidate the reason for seperate header files .

William.