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:
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.
Generated on Sat Jan 13 17:20:21 2007 for Flatland by doxygen 1.5.1