News:

Simutrans Chat Room
Where cool people of Simutrans can meet up.

Code style document

Started by Max-Max, May 27, 2013, 10:36:59 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

Max-Max

The coding document don't specify the preferred indentation size and if it should be tab or space characters.
Is it 2 spaces for both indentation and tab? (spaces instead of tab character)...
- My code doesn't have bugs. It develops random features...

TurfIt


prissi

I use 2 and 4 also sometimes. The beginning of a line should be tabs; after that spaces (i.e. when continuing if brackets).

Definitions should rather use spaces.

But that point again at reworking the dokumentation.

Max-Max

#3
At my former work we had some pretty good coding standard, similar to the ones here. We took the best from Ericsson and Tagilent to create a light version of them.

If you are to rework the document, maybe you can find some of our coding style useful.

Function parameters get the prefix f, this to avoid conflicting names with local/class variables. This was also useful to see if it was a parameter or a local/class member.
We had a name standard where function names always started with a small letter and then every word beginning with a capital.
Variables always started with a capital letter and then followed the same standard as for function names.
We used the prefix g for global variables to alert new coders (and our self) that this is serious business to play with :)
Pointers got the prefix p.

All #defines where always after the last #include and before the first function, all in capital with _ between words.
All variable declaration was always at the top of each function, even temporary ones...
const and enum values always start with a small k.
enums always start with a Capital E followed by a name in plural.
Classes always started with a T (old habit from Borland's framework)

Since we where working with embedded systems with very limited memory we used enum instead of const. A const is in fact compiled in as a variable because you can point to it (well some compilers are intelligent enough to optimize this), while an enum value is always compiled in as a true constant.

We always declared struct as an typedef and bits as a union so they can be accessed all at once.

In if statements we tried to put the constant first when comparing to catch missing =

if( EComStates::kIdle = gComState ) will generate an compiler error while if( gComState = EComStates::kIdle ) may generate yet another bug hard to find.

enum EDragStates {

    kIdle,   //!< No drag operation in progress
    kDrag, //!< Drag operation in progress
    kDock  //!< Dock operation in progress

};

class TWindow : public TControl {

    public:
      void setSize(int fSize);

};

void TWindow::setSize(int fSize) {

    int n; // Well the usual temp variables n,j,i,x,y,z are in lower case :)
    void* pArbitraryPointer = NULL;
   
    if(  false == gFullScreen  ) {
      Size = fSize;
    }

}


Well, maybe you can find some of it useful. If you are interested I can see if I can find the document, but I think I covered the most here...
- My code doesn't have bugs. It develops random features...

Ters

Interesting to see what styles some use. The T-prefix reminds me of a database at work, which uses a T-prefix for all table names, and another prefix for columns. This is a bit annoying as these prefixes occupy a significant part of the short maximum name length (25 % for table names).

However, most of this is about naming, which I don't think we're going to change as it definitively breaks patches and forks, and Simutrans is quite standardized in that area. The main areas where Simutrans is all over the place when it comes to coding style is spaces, and where to put braces.

Quote from: Max-Max on May 27, 2013, 11:56:13 PM
All #defines where always after the last #include and before the first function
This doesn't work when the behaviour of the include file can be controlled with #defines. Simutrans' own headers that are controlled this way usually get such #defines' passed from outside the compiler, but there are system or library headers where it makes more sense to put these headers in the source code, mostly because they're fixed and not something that changes from build to build. A typical header guard also doesn't follow this rule, although I think it can with some reduced effectiveness. But it's a good rule of thumb.

Max-Max

Well without rules you can't make exceptions :)

We had also some configuration files included in some other places and of course the header guard. configuration files was not called .h but .cnf or .inc to distinguish them from ordinary .h files These where the exceptions.

When I think of it we also did a comment header in front of each function in the .cc file. It didn't only separate a function from another but also gave the programmer the needed information in the same file he worked on.

When writing Windows application we always put the gui class name at the end of the variable name. This was an effective way to group controls together and prevent the names from colliding.

file_name_label
file_name_edit
file_name_panel


It is easy to see that these 3 controls are used together in the GUI.

Well I know that you use another naming standard and it makes no sense to change that. But maybe the global prefix g would be worth the effort to use. It is a quite important thing to notify the programmer on.

I'm so use to some of these standards that I don't even think about it. I often find myself using the wrong coding style and have to change back to Simutrans standard  :P

This was only a reflection of how we did it, you may of course use whatever you like or nothing of it...
- My code doesn't have bugs. It develops random features...