This page contains resources concerning source code formatting. Please read it (and related pages) carefully before contributing code. Thank you!

Table of Contents

1. About Formatting
2. General
   1. General Rules
   2. Documentation
      1. Special Comment Styles
3. Languages
   1. C++
   2. Java

About Formatting

This pages contain information and rules about how to format your code. Having some (more or less) tight rules for formatting is important, as it keeps code consistent and easier to read and maintain.
However, these are less to be seen as "law" but rather advice, i.e. where it makes little to no sense applying this rules: Don't!

General

First of all: The concrete formatting might heavily depend on the programming/scripting language used from case to case. Thus, refer to the relevant pages about specialized formatting or create one yourself, where to collect the rules for that language.

Nevertheless, this section shall give general advice, that probably applies to every language.

General Rules

• Use 4 spaces for indentation.
• Don't use tab characters. Make sure your editor inserts spaces instead of characters. Tab characters are displayed very differently from editor to editor, thus, it is better to avoid them. You can however use them where they are mandatory (e.g. Makefiles, where tabs are part of the syntax).
• Keep lines short. Generally, try to keep single lines below 80-90 characters. If not practicable, try to keep
  lines at last below 150-160 characters (everything beyond is difficult to handle, even with a decent resolution).
• After statements like if or while, a lot of languages allow to either place a complete block of core or just a single statement. Always use the block there (i.e. in C-like languages, insert the braces):
  
  //Correct:
  if (test)
  {
  myFunc();
  } else
  {
  prntErr();
  }
  //Wrong:
  if ( test )
  myFunc;
  else prntErr();
• Block delimiters (as braces in C) come into their own line, i.e.:
  
  function test()
  {
  printf( "Hello world" );
  }
• Leave spaces between symbols and text/numbers. Leave a space between a opening parentheses and the first text that follows. Also leave a space between the last text and the following closing parenthesis:
  
  function test( int a, int b )
  {
    if ( a > 0 )
    {
      return test( a - 1, b + a );
    }
    else
    {
      return b;
    }
  }

Documentation

In-code documentation is preferred over external. This is, because in-code documentation can be used immediately without other tools. Generally: Document everything! Even if code is (currently) not supposed to be published or worked on by others it might also be useful for yourself.

At last, you shall document document "header" files, i.e. files that others are supposed to work with. You might leave internal header files and source files undocumented. Also, you also do not need to document parts of an header that is not for "external use", e.g. private class members.

Generally, keep in mind: The documentation shall help others to quickly understand what your functions/classes do without the need to read through your complete project!

Special Comment Styles

For a lot of languages there are special tools that extract documentation from the files and build e.g. HTML or PDF documentation files. Thus, you are heavily advised to use the "comment syntax" required by such. Please consult the language specific pages for more details.

Languages

C++

See the Code Formatting (C++) page for further details.

Java

Widely use the same rules that apply to C++, too. However, it is common in Java to put the opening brace of a block in the last line, thus, you might use this rather than the strict rules that apply to C++.