Source code consistency

[Jebbs]

Basically, I was working on a project and thought to myself that I could do a much better job at being more consistent with the over all layout of my code and I was wondering if there were certain rules or guidelines that SFML uses for its source and how that process works. When I talk about consistency, I am mainly talking about how the layout of  each file is structured in terms of what things go where and in what order, and how things are named.

How does everyone here keep their stuff clean and consistent? Do you have your own set of rules you follow? Does it even matter to you?

[georger]

Basically, I was working on a project and thought to myself that I could do a much better job at being more consistent with the over all layout of my code and I was wondering if there were certain rules or guidelines that SFML uses for its source and how that process works. When I talk about consistency, I am mainly talking about how the layout of  each file is structured in terms of what things go where and in what order, and how things are named.

How does everyone here keep their stuff clean and consistent? Do you have your own set of rules you follow? Does it even matter to you?

To me it matters a lot. I follow these guidelines in my code:
- I use camel case and avoid abbreviations like the plague;
- I create a namespace for the project's classes;
- My classes have public interface first, then protected, then private;
- In class declarations: first enums, then member variables, then member functions;
- I use spaces and empty lines to make the code more readable (to me);
- All the code is formatted with Artistic Style, and looks like this:

#include <iostream>

using namespace std;

class Singleton
{
public:

    static Singleton & getInstance()
    {
        static Singleton singleton;

        return singleton;
    }

    void print()
    {
        cout << "I'm a singleton!" << endl;
    }

private:

    Singleton() {}
    Singleton( const Singleton & );
    Singleton & operator=( const Singleton & );

};

int main()
{
    Singleton::getInstance().print();

    return 0;
}

What I need to improve is the comments. I don't comment nearly as much as I should.

[Jesper Juhl]

I find that it matters a lot.

I use clang-format - http://clang.llvm.org/docs/ClangFormat.html - with a customized rules file to manage the layout of my source.

I also have a set of rules that are not related purely to source formatting. A few examples:

• always catch exceptions by (const) reference
• use stl algorithms and avoid naked loops when possible
• no global variables (which includes singletons)
• never duplicate code, use helper functions and build libraries
• don't reinvent the wheel, use existing  libraries when available
• alwais use RAII and avoid manual memory management
• always use explicit, override, const etc where applicable

and more...

Of course there can be exceptions, but I find that to be rare. If I do have to stray from one of my rules then I have another rule that the reason for the exception must be clearly commented in the code.

[Nexus]

How does everyone here keep their stuff clean and consistent? Do you have your own set of rules you follow? Does it even matter to you?

I have such a set of rules, but they're not explicitly stated anywhere. For example, inside class the general order of member declarations is public, protected, private, and I use separate sections for member variables, member functions and types. Members are indented to have a better overview. Global functions that are not part of the interface are defined at the beginning of the .cpp file, possibly in an anonymous namespace. Global functions in the API of a class are declared after the class definition, and defined at the end of the .cpp file. I keep the order of function declarations and definitions consistent. Naming convention is of course important too, but they're easy to follow.

Apart from syntactic conventions, code style is also important for me. This thread probably summarizes my view of good C++ code the best.

[eXpl0it3r]

Just putting this here: Some have once started to write a Style Guide for SFML, so contributors would have it easier, you can find it here on the wiki.

Personally I think, you should just find a way that fits your needs and stick with it, as long as you make it consistent.

[select_this]

I use K&R code styling, modified to suit my tastes better e.g. everything inside a class declaration is indented. Public interface always comes first, as you would expect.

I only ever use spaces as well, no tabs, though I understand the arguments for going for the opposite (just don't mix them, ever!)

I *REALLY* don't like the whole 'put the opening curly brace on a newline' thing that I see everywhere nowadays 

[SeriousITGuy]

Yeah it matters heavily to me. It makes code more readable to me AND I make less errors. I took a look at some good examples and tailored my own coding style from it. Here are my most important coding rules:

- Use speaking names for variables/functions and use correct camel casing (starting with a lower case and every new word with an upper case). Avoid abbreviations!
- Avoid vertical space waste, opening curly braces are on the same line then the statement: if( _isPaused ) { ...
- Indent only inside braces  if( _isPaused )
- One line conditional statements are always enclosed by curly bracers
- In class definitions public interface comes first, followed by public members, then protected functions and members, then private functions and at last private members.
- Private class member names start with an underscore: sf::RenderWindow _window; (I don't like the often used m as a starting character)
- Indent member names in class definitions to make nice looking columns, but only in each public, protected, private block
- Always use #pragma once in the beginning of every code file (traditional include guards are ugly and serve no purpose anymore since every prominent compiler uses #pragma once)
- Use multiple namespaces for the project to separate e.g. engine, entities, game states etc.
- Always use STL algorithms and containers, use smart pointers and RAII, avoid manual memory management like the plague
- Use const as much as possible! It helps avoiding stupid bugs!

I have more rules, but these are the most important to me. Since following them, my code became much cleaner and more bug free. Especially the use of const helped me much

Good luck in finding your own style.

[slotdev]

We've got 5 coders in my game dev company. All have their own style - some are very modern, camel-case, one is VERY old style (is from asm background) and whose code looks like a car crash.

This makes is quite hard for everyone else to understand what is going on, but you can't teach an old dog new tricks.

Remember the goal is to make the code smaller, more robust and easy to learn. Doing this means smaller learning curves and therefore, shorter development timescales.

Some of our guidelines:

1. Using the “broken window” theory (Google it!), poorly written code and hacks/bodges only encourages more bad code and hacks to already hacked code. Soon you end up with total spaghetti, incomprehensible and a disaster in waiting.

2. Treat all warnings as errors. This means that a build should happen without any warnings of any description – no matter how trivial. Leaving minor warnings such as signed/unsigned mismatches is sloppy and a bad example to other coders.

3. Use C++ casts instead of old style C casts – in C++ casts, the compiler checks the cast is valid and not going to cause problems at runtime (between int and char pointers especially).

4. Don’t use const char strings. This is 2014 not (C) 1989.

5. Think carefully when using default arguments. It makes code hard to read (as the function definition doesn’t match the call).

Ed