Coding Style and Standard

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:

programmers can go into any code and figure out what's going on
new people can get up to speed quickly
people new to C++ are spared the need to develop a personal style and defend it to the death
people new to C++ are spared making the same mistakes over and over again
people make fewer mistakes in consistent environments
programmers have a common enemy :-)

Bad Points

Now the bad:

the standard is usually stupid because it was made by someone who doesn't understand C++
the standard is usually stupid because it's not what I do
standards reduce creativity
standards are unnecessary as long as people are consistent
standards enforce too much structure
people ignore standards anyway

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

No Tab character: Make sure all tab character converted to 4 spaces.
Indent level: One indent level is 4 spaces

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

软件开发规范