style guide

Commenting

Perry teaches the following concerning commenting.

• Do it. Comments allow you and others to get back into the zone faster.
• Comment your thinking not what you're doing. Anyone reading the code knows what i++ means. Don't comment "increment i"
• The bulk of your comments should come before the function where you describe the purpose of the entire function - what are your expectations for it? Any assumptions? What side effects does it have? Break out exceptions that leave the function separately as they are side effects.
• Use this template:

/*  FUNCTIONNAME() - This function

    Parameters:

    Returns:

    Side Effects:

    Expceptions:

*/

Whenever you have something serious to bring our attention to use:

// NOTE:
// NOTE: The comment
// NOTE:

The prefix and suffix are necessary.

RETURN VALUES SHOULD BE CHECKED

If it at all matters, do it!

Points of return / function exits

Should be kept to one. At the bottom.

Indenting

Tab stops set at 4. No Exceptions

Braces

Whoever adds to a source file must adhere to the bracing style already present in that file.

The preferred style is the brace-on-newline style:

if (bool)
{
}
else
{
}

while (bool)
{
}

Function declarations, commas and references / pointers

type NameOfFunction(type arg1, type * arg2, type & arg3)

Variable and function naming

Nothing extraordinary here.

Functions begin with caps. Variables don't.

Functions are camel back. No exceptions.

Variables should be words_split_with_underscores. However, if you're the first author of a file you can choose a different style. Second or later contributors must follow the variable naming style found in the file.

Constants ought to be ALL CAPS but not always. If they are shared between functions or methods, they should be ALL CAPS.

Use descriptive variable and function names. Typing is finite. Debugging is not.