Coding Standards

From KruelWiki

liordeltro Along with following these implementation specific instructions, I'd suggest you also read through the coding practices page. This document applies to C++ and Java only. Ask if you wish a standard to be developed for another language.

Related Links:

• PHP Coding Standards

Contents 1 Documentation 1.1 TODO Items 2 Case 3 Filenames 4 Syntax 5 CVS 6 General Stuff

Documentation

1. Any public class, method, variable, enum or typedef you create must have accompanying Doxygen information.
2. You should add Doxygen documentation for any private classes, methods, variables, enums or typedefs, but this is not absolutely required.

TODO Items

Put todo items in code as a comment in one of 3 ways:

• //FIXME: <description>
  Identifies an error that will cause incorrect operation the code
• //TODO: <description>
  An improvement that should be done before release
• //XXX: <description>
  A note or question to be read by other coders, and removed when agreed apon

Then it's far easier to grep and find things that need doing that might be too small or trivial to create a task for. Larger issues should be created as a task on the kruel website for the project.

Case

1. Class names start with a capital letter, and are StudlyCaps. e.g class ThisClassType
2. variables, methods, members, object instances must use camel case e.g. int thisVariableName;
3. #defines, enums and macros are all UPPER_CASE, with spaces represented by underscores

Filenames

1. ALL directories are in lowercase. No exceptions.
2. Header files end in .h, C++ in .cpp, C in .c, Assembly in .asm
3. Filenames that contain details about a class should be named the same as the class: eg. MyClassDefinition.cpp
4. There must be a single .h file for every class. Where required, there should be a single .cpp for every class.
5. Spaces are not permitted in filenames. Use an underscore if you need to split words clearly.
6. The names for entry point files (ie. those with a main() method) should be in lower case, eg. praelium.cpp

Syntax

1. Opening braces start following the statment they refer to (see switch example below). The first line of code starts on the next line. Closing braces are on a line by themselves.
2. 4 columns indent. One tab character should used, and be redefined in the editor of your choice to be 4 columns. This means the agnostic indenter can use a different value to setup their editor.
3. Declare variables (when practical) at the beginning of a block, and separate variable declaration with code by a blank line.
4. Opening paren for if, switch, do, while is separated from the construct by a single space.
5. Opening paren for function / method / macro calls is joined to construct name.
6. Parameters are separated by a comma and a single space. e.g. func(param1, param2, param3);
7. Switch follows this layout:

 switch (variable)  {
     case 1 :
         doSomethingHere();
         break;
     default :
         doSomethingElse();
         break;
 }

CVS

1. ALWAYS run make before you commit. I don't want to see code that doesn't compile ever committed.
2. Write a useful changelog when you commit. "Fix stuff" is not good enough
3. Update before you start working on a piece of code
4. cvs annotate is not useful (so don't use it). You don't need to blame someone if their code is broken, you need to fix it.

General Stuff

1. Avoid globals if at all possible (which it should be). If something is part of a class, put it there.
2. If you see something is broken (not working) then fix it.
3. There is no code ownership. This does not give you leave to go changing people's code because you don't like the layout. You can change code to implement new features that you need.
4. Don't implement features unless they are needed. If you find legacy code that is no longer used, remove it. It can always be recovered from CVS if it is found to be required.
5. If your compiler allows it (and I know GCC does), configure it to give you all possible warnings. This is normally done using -Wall and will help with portability and reliability of code.
6. Don't ignore compiler warnings! They are there for a reason! Consider them a bug.