About: Coding Rules

Required Rules
01

General

There are many coding rules, and nearly all of them share some common things that can be summarized with the term 'common sense' nowadays.
This common sense includes naming the things about what they do/are, writing functions of less than about two to three monitor pages (Yes, depends on resolution and font size...) and the like. 		Look at existing code to copy its format.
02

There are more rules than written here that I follow - those listed here are the most important ones.

03

Jump Statements

  • The statements 'goto' and 'continue' are prohibited.
  • A 'break' is only allowed once as the last statement of a 'case' block.
  • A 'return' is only allowed once as the last statement of a function.
 Any construct can be written under these rules. Look at the code if in doubt.
04

Names

  • Defines are in all uppercase characters, words separated by one underscore.
  • Local variables start with a lowercase character
  • Member variables start with the character 'm' and continue with an uppercase character.
  • Global variables start with the character 'g' and continue with an uppercase character.
  • Pointer variables (additionally) start with the character 'p' and continue with an uppercase character - context (global/member) comes first: *pData, *mpData, *gpData.
  • Functions start with an uppercase character. Exception: Java uses lowercase.
  • Different case shall not be the only distinction between two objects.
  • Abbreviations should only be used if their meaning is obvious.
05

Context of variables

Variables should be declared as local as possible. Exceptions can be with often used counter variables or performance considerations (constructor/destructor).
06

Global variables

There shall be as few global variables as possible. While C code often needs them, code of object oriented languages should at least use static member variables.
07

Marker

Blocks that require some attention (unfinished, bug, problem, ...) are to be marked by five (5) exclamation marks at the beginning of a comment and a further descriptive text. 		Personally I don't like these TODO or BUG or whatever words.
08

Function separator

Functions shall be preceeded by one comment line, ending at column 78:
C: 
/* ------------------------------------------------------------------------ */
Others: 
//----------------------------------------------------------------------------
09

Class/Section separator

Classes and sections should be preceeded by one comment block, ending at column 78:
C: 
/****************************************************************************/
/* section ClassOrSection */
Others: 
//////////////////////////////////////////////////////////////////////////////
// section ClassOrSection
Their use is not enforced for /every/ place.
10

General Format

  • Binary and Tertary operators are enclosed by one space.
  • Brackets of a block {} are on a dedicated line each, using the indentation of their parent block.
  • The opening bracket after a reserved keyword is separated by one space. (Except for function calls like super(...) )
11

Constant NULL (C/C++)

The constant 0 shall be used for a reset pointer value.
 Awkward at first, I now like it to do it that way. (And even 4 keystrokes less ;)

Recommended Rules
12

Tabulator width

Generally there should be no assumption on the configured tabulator width. (This has already been bent by the function separator line).
Semys was and is written using a tabulator width of 2.
13

Names of container classes

  • Lists: content + 'List'; ConnectionList
  • Maps: content + 'By' + key + 'Map'; ConnectionsByIdMap
Reason: One common defined way to name these.
14

Use of defines (C/C++)

Generally, there should be as few defined constants as possible. For integers, use enums; Strings should be stored as static members.
Reason: Defines are often overused - Java and C# hardly even have them anymore.
15

Length of source lines

A new line should be used after reaching the area between columns 80 - 110.
The current statement should be continued in the next line with one more indentation level.
Reason: vertical scrolling reveals much more information at once than horizontal.
16

C Boolean type

int32 or int shall be used for boolean (true(!0), false(0) ) variables.
Reason: C has no standard boolean type, and before any different type is encountered, one is defined.

Examples
17 
int gInit = 0;

/* ------------------------------------------------------------------------ */

Object *InitExample(void)
{
  int i, result = 0;
  Object *pObject = 0;

  /* !!!!! Seriously, what does this loop do? */
  for (i = 0; i < 32 && result <= 1000; i++)
  {
    uint32 mask = 1 << i;

    if (mask & 0x00000001)
    {
      result = OtherFunction(i);
      printf("Hello");
    }
  }
  if (result > 1000)
    pObject = new Object(result);
  gInit = 1;

  return pObject;
}

Goto: Main Page; This page is part of the Semys software documentation. See About: Documentation for details.