Flatland Documentation

Style Guidelines

Whitespace

• Use 4 spaces for indention. Do not use tabs. Do not put spaces on blank lines or at the end of lines.
• Do not place whitespace immediately after an open-paren or before a close-paren.
• One space should go before the open paren.
• Outermost curly braces should start at column 0.
• Binary operators should have spaces on both sides.
• Unary operators should not be followed by spaces.
• Commas should be followed by spaces.

Names

• Globals are capitalized.
• User-defined types are capitalized.
• Small frequently-used types designed to mimic GLSL or STL are allowed to break capitilization rules (eg. vec3, iterator).
• Use camel caps rather than underbars for word seperation (except when mimicing STL).

Class Layout

• Members should be ordered public, then protected, then private.
• Public members are capitalized.
• Access specifiers (public, protected, private) should be half-indented (two spaces).
• Event handlers are prefixed with On.
• Member data should never be public unless they are const and static.
• Do not inline methods that are more than one line long.

Example class:

class ExampleClass
{
  public:
    ExampleClass(int a);
    ExampleClass();
    ~ExampleClass();
    void OnMouseMotion(const Event& e);
    void OnKeyDown(const Event& e);
    void OnKeyUp(const Event& e);
    static const int Count = 5;
  private:
    int data[Count];
    bool ready;
};

Curly Braces

• For a single-line "then" clause, do not use braces unless the "else" clause is multi-line.
• For a single-line "else" clause, do not use braces unless the "then" clause is multi-line.
• A single-line loop body should not have braces.
• Opening braces should be on a line by themselves, except for simple 1-line functions, in which case the opening and closing braces are on the same line.

Headers

For header guards, use "#pragma once" rather than ifndef HEADER_H. The pragma is supported on most modern compilers.

Parameter Passing

For passing objects that can be modified by the routine, use a pointer. For passing objects that should not be modified by the routine, use a const reference. These rules also apply to structs. If the struct is 8 bytes or less, it may be passed by value for convenience. Note that modern C++ compilers will often optimize these cases by passing via registers instead of the stack.

Comments

• In general, use double-slash comments rather than slash-asterisk comments.
• Do not make horizontal rules out of comments like /////////////////////// or //------------- etc. If you want a visually obvious divider, consider making a separate file instead.
• Use doxygen annotations in your comments. Include triple-slashed brief and detailed descriptions for all noteworthy classes and structs.
• For descriptions of functions or classes, write capitalized sentences with periods that are descriptive rather than imperative. eg: "Draws the given image.", "Maintains a texture.", "Responsible for cleaning up."
• For comments that describe actions within a functions, use lower case with no periods and write imperative sentences. eg: "initialize the context", "transform the file name"
• The top of every file should look like this:

// Summary: Test for circle-circle intersection and generate contacts.
// Copyright: 2007  Philip Rideout.  All rights reserved.
// License: see bsd-license.txt

Pointers

• When declaring a pointer or reference type, juxtapose the asterisk or ampersand with the variable, not the type. For example:

const char *s;
const TClass &instance;

Enumerations

Large enumerations should be generated by modifying enums.txt, which is used by enums.pl to generate Enums.h. The perl script generates an enum encapsulated within a struct which provides the following:

• Namespace for the enumerants.
• Same memory footprint as an unsigned int.
• Automatic enumerants for "Count" and "Invalid".
• The generated code has the integer values listed explicitly.
• Implicit conversion with unsigned int.
• Names will show up in a debugger.
• Increment/decrement operators for easy loop construction.
• enum-to-string conversion. If you don't want to use the auto-generated string name, then you may optionally provide your own.

Misc

• Prefer prefix increment to postfix increment.
• There is no limit on line length.
• Because we use camel caps, acronyms should not be all caps.
• Namespaces should not have trailing semicolons. Wrapping an entire header file in a namespace block is fine, but try not to wrap an entire cpp file in a namespace block.

---