Brief Coding Style and Standard


Standardization is Important

It helps if the standard annoys everyone in some way so everyone feels they are on the same playing field. The proposal here has evolved over many projects, many companies, and literally a total of many weeks spent arguing. It is no particular person's style and is certainly open to local amendments.

Good Points

When a project tries to adhere to common standards a few good things happen:

Bad Points

Now the bad:

Discussion

The experience of many projects leads to the conclusion that using coding standards makes the project go smoother. Are standards necessary for success? Of course not. But they help, and we need all the help we can get! Be honest, most arguments against a particular standard come from the ego. Few decisions in a reasonable standard really can be said to be technically deficient, just matters of taste. So be flexible, control the ego a bit, and remember any project is fundamentally a team effort.


Code formatting

Indentation

Brace

Use Braces "{}" to mark the beginning and end of all compound statement aligned vertically with their parent block.
while (foo)
{
    if (bar)
    {
         Yabba(dabba);
    }
    else
    {
        foo();
    }
    Xyz(abc);
}


Comments (Clear and necessary)

You can simply copy and paste the following comments before file header and functions to your code.

File headers

/*****************************************************************************\

Department of Mathematics, Zhejiang University
Copyright (c) 2004 Department of Mathematics, Zhejiang University

Author

    ID, name, email etc.

Module Name:

An unabbreviated name for the module (not the filename)

Abstract:

Description of what this module does

Notes:

[Optional] Additional notes about this module - things that may help
the reader of this code later on. Examples are: algorithm description,
special case conditions, references, etc.

History:

Created on mm/dd/yyyy by email-name
Modified on mm/dd/yyyy by email-name
[Optional] history description

\*****************************************************************************/

Section separators

//-----------------------------------------------------------------------------
a commented one

//-----------------------------------------------------------------------------
// Buffer manipulation routines
//-----------------------------------------------------------------------------

Function headers

/*****************************************************************************\

Function Description:

Description of what the function does

Arguments:

[<blank> | OUT | IN/OUT] argument-name - description of argument


Return Value:

return-value - description of return value
or NONE

History:

Created on mm/dd/yyyy by email-name

\*****************************************************************************/


More

C++ Coding Standard