Skip to content

Latest commit

 

History

History
105 lines (85 loc) · 3.53 KB

CODING_GUIDELINES.md

File metadata and controls

105 lines (85 loc) · 3.53 KB
Raw

Coding Guidelines

Stick to the principles of Object Oriented Design

Read more about this wonderful concept here.

Leave the code cleaner than you have found it

Use comments to describe the why, not the how

Conventions

File encoding and line endings

  • The source files may be restricted to ASCII encoding, or use UTF-8 without BOM (this warning specifically targets developers using Windows).
  • Line endings may be LF or CRLF, although the former is preferred. CR line endings are not valid.
  • Encoding conversion macros (L"", _T(""), T(""), …) are considered a plague and will be rejected (unless they are in platform-dependent source files which only gets compiled on those platforms).

Preprocessor

Include guards

Include guards have an uppercase name reflecting the current header file name, and are terminated by _HPP.

They are not to be prefixed or suffixed by any underscore.

In fact, all global names (that includes defines) starting with one underscore and a capital letter or two underscores are reserved by the C and C++ standard. As of the 2012-01-16 C++11 Working Draft, this is specified in 17.6.4.3.2/1 [global.names].

(Yet, many developers keep using this bad practice)

As a side note for MSVC developers: #pragma once isn't an include guard and can't replace it. It can supplement it but be aware that it has no effect on sensible compilers (which have an include guard optimization, effectively nullifying the need for those pragmas), i.e. not MSVC. Except for Windows-specific source files, any file only containing it will be rejected.

Indentation, whitespace and line length

  • An indentation level = two spaces. Tabs aren't considered a consistent identation method.
  • Empty lines are not to be indented, i.e. really empty.
  • There may not be more than 2 consecutive empty lines.
  • Namespace blocks does not indent, nor are switch's case labels.
  • When additional identation would make the code more legible (e.g. chained variable declarations), more spaces can be added if their count is low; else, just increase the identation level by one.
  • Trailing whitespace isn't allowed.
  • Maximum line length is 100 UTF-8 codepoints. In layman terms, 100 characters.
namespace radix {

void func() {
  int i = 0;
  switch (i) {
  case 0:
    break;
  default:
    break;
  }

  // The following is correct, additional whitespace is low
  int a = 1,
      b = 2,
      c = 3;

  // The following isn't correct, too much whitespace
  std::unique_ptr<int> ptrA(new int),
                       ptrB(new int);

  // Use the following instead:
  std::unique_ptr<int> ptrC(new int), ptrD(new int), ptrE(new int), ptrF(new int), ptrG(new int),
    ptrH(new int);
  // Here, the line wrapped because we hit the 100-character limit
}

} /* namespace radix */

Pointer and References

Pointer/reference mark sticks to the variable name (not function name), or when there is no variable name, to the type itself.

Type var1, *var2, &var3 = thing;
Type* getPtr(Type *namedParm);
Type& getRef(UnnamedParm*);

// The following is inherently stupid legibility-wise:
Type *idiotGetPtr(Type *namedParm);
// because it doesn't return Type, it returns Type* !

Blocks of code

  • Always open a new block of code after a control structure
  • Open them on the line of the control statement
  • Put code on the next line
if (cond) {
  code();
}

// The following is bad:
if (cond)
{
  code();
}

if (cond)
  code();

if (cond) code();