1. Introduction
Most basic concept of C++ style rule is Use common sense and always be consistence inside the project.
Most common logic of software development is that 10% of the cost of a project goes into writing code, while more than 50% is spent on maintaining it.
Think about the trade-offs between ease-of-programming now vs. ease-of-maintenance for the next 5 to 10 years when you consider the recommendations presented here.
The establishment of a common style will facilitate understanding and maintaining code developed by more than one programmer as well as making it easier for several people to cooperate in the development of the same program. The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you are saying, rather than on how you are saying it. This document present global style rules here so people know the vocabulary. But local style is also important. If code you add to a file looks drastically different from the existing code around it, the discontinuity throws readers out of their rhythm when they go to read it. Try to avoid this. If you are editing code, take a few minutes to look at the code around you and determine its style.
2. Coding conventions
2.1. Files
- There should be one include class declare header file for each source code file.
- Each include file should describe a single class or tightly integrated set of classes.
- The name of the file should be the name of the class contained in the file without the leading "C". And file names should begin with lower case letters.
- File names should limited up to 30 characters.
- File names and directory paths should not contain blanks, parentheses "(", or crazy characters
- File header comments shall be placed at the top of each file stating the name of the file and comments on the file contents [Appendix 01].
- Do not use filenames that already exist in STL Fine names should be lowercase and words separate by underscore sign.
- Each project should have a readme.txt file
2.1.1. Header Files(.hpp)
- Header files should only to contain definitions and NOT instantiations. Thus the include file can be used in multiple files.
- All header files should have #define guards to prevent multiple inclusions.
- The format of the symbol name should be FILENAME
_H_. - Do not use #pragma once.
- If a class in a header file does not need to know the size of a data member class or does not need to use the class's members then forward declare the class instead of including the file.
- When including use standard order for readability and to avoid hidden dependencies: C library, C++ library, other libraries' .hpp, your project's .hpp.
- Within each section, includes should be ordered alphabetically.
- Do not include files with full path. Include statements should be documented, telling the user why a particular file was included.
- If the file includes a class used by the class then it's useful to specify a class relationship.
- C++ header files often use the suffix ".hpp" while "C" header files use ".h" suffix.
- Avoid the use of "namespace" in the ".hpp" include file.
2.1.2. Source file(.cpp)
- C++ source files should have a .cpp extension. Each source file should always have a header file with same name and a .hpp extension.
- The source file defines code and It instantiates definitions defined in the include file.
2.1. Namespace
- Unnamed namespaces in .cpp files are encouraged.
- Do not use a using-directive outside the classes in .hpp files.
- You may use a using-declaration anywhere in a .cpp file, and in functions, methods or classes in .hpp files.
- Do not use unnamed namespaces in .hpp files.
- Namespaces wrap the entire source file after includes, definitions/declarations, and forward declarations of classes from other namespaces.
- Do not use namespace aliases are outside of the named namespace in .hpp.
- Namespace names should be all lower-case.
2.2. Class and structures
- Be sure to add virtual to the base class destructors.
- Access modifier sequence should be public, protected then private and the declaration order should be
- Typedefs and Enums
- Constants (static const data members)
- Constructors
- Destructor
- Methods, including static methods
- Data Members (except static const data members)
- Avoid doing complex initialization in constructors (in particular, initialization that can fail or that requires virtual method calls).
- When redefining an inherited virtual function, explicitly declare it virtual in the declaration of the derived class
- If class doesn’t have other constructors you must define a default constructor (one that takes no arguments) and use to initialize the members.
- Use the keyword explicit for constructors with one argument except copy constructor.
- Do not overload operators except in rare, special circumstances
2.3. Functions
- Define functions inline only when they are small, say, 10 lines or less.
- Try to keep function short and simple (around 40 lines).
- When defining a function, parameter order is: inputs, then outputs.
- Write some descriptive comments before every function, telling the user what you did and why.
- Use completely global functions rarely and put nonmember functions in a namespace avoid polluting the global namespace.
- Place a function's variables in the narrowest scope possible, and initialize variables in the declaration.
- Function names should be descriptive; eschew unknown abbreviation, should be "command" verbs.
- Regular functions name should start with a capital letter and have a capital letter for each new word. No underscores.
- Accessors and mutators (get and set functions) should match the name of the variable they are getting and setting
2.4. Variables
- Variable names should be descriptive; eschew unknown abbreviation types and should be nouns.
- Name should be lowercase and use underscore to combine nouns (my_variable)
- Class member variables have trailing underscores (my_variable_)
- Declare object variable used in a loop outside that loop.
- Variables are to be declared with the smallest possible scope.
- Avoid local variable definitions that override (hide) variables defined at higher levels.
- Try not to use Static or global variables of class type.
- Consider to use const in possible locations.
- Try not use variable length arrays, use vectors instead.
- Data members in structs should be named like regular variables without the trailing underscores that data members in classes have.
- Use prefix g_ with global variables. But discourage to use global variables.
- Use prefix c_ for constants variables.
- Do not use Hungarian notation
- A global variable would be instantiated in the ".cpp" file and NOT the ".hpp" file
2.5. Comments
- When writing your comments, write for your audience: the next contributor who will need to understand your code. Be generous.
- Start each file with license boilerplate, followed by a description of its contents with header comments.
- Do not duplicate comments in both the .hpp and the .cpp.
- Every class definition should have an accompanying comment that describes what it is for and how it should be used.
- Every function declaration should have comments immediately preceding it that describe what the function does and how to use it.
- What the inputs and outputs are should comment in function definition.
- If there ant special things to mention about the function, It should comment above the function definitions (How it does the job).
- Each class data member (also called an instance variable or member variable) and global variables should have a comment describing what it is used for.
- In your implementation you should have comments in tricky, non-obvious, interesting, or important parts of your code. But not everywhere.
- Note that you should never describe the code itself. Assume that the person reading the code knows C++.
- Use TODO comments with your email for code that is temporary, a short-term solution, or good-enough but not perfect. (TODO(kl@gmail.com): Need to implement thread safe.)
2.6. Formatting
2.6.1. Function declaration and definition
-
Simple function
ReturnType ClassName::FunctionName(Type par_1, Type par_2){ DoSomething(); ... } - With long argument list.
ReturnType LongClassName::ReallyReallyReallyLongFunctionName( Type par_1 Type par_2, Type par_3){ DoSomething(); ... } - The return type is always on the same line as the function name.
- The open parenthesis is always on the same line as the function name.
- There is never a space between the function name and the open parenthesis.
- There is never a space between the parentheses and the parameters.
- The open curly brace is always at the end of the same line as the last parameter.
- The close curly brace is either on the last line by itself or on the same line as the open curly brace.
- All parameters should be named, with identical names in the declaration and implementation.
- All parameters should be aligned if possible.
- If some parameters are unused, comment out the variable name in the function definition for future use.
2.6.2. Function call
- Simple function call
bool retval = DoSomething(argument1, argument2, argument3);
- If the function has many arguments, consider having one per line if this makes the code more readable.
bool retval = DoSomething(argument1, argument2, argument3, argument4);
2.6.3. Conditionals
- Simple condition.
if(condition){ ... }else if(...){ ... }else{ ... } - Short conditional statements may be written on one line if this enhances readability.
if (x == kFoo) return new Foo(); if (x == kBar) return new Bar();
- Do not write short conditional statement when the “if” statement has an “else”.
if (x == kFoo){ return new Foo(); }else{ return new Bar(); }
-
When you have a Boolean expression that is longer than the standard line length, break up to the lines.
if (this_one_thing > this_other_thing && a_third_thing == a_fourth_thing && yet_another && last_one) { ... }
2.6.4. Loops and switch statements
- Simple switch always should have default and break.
switch (var){ case 0: ... break; case 1: ... break; default: assert(false); }
- If the content of the cases are too long should use curly brackets.
switch (var){ case 0:{ ... ... ... ... break; } default: { assert(false); } } - Simple while loop.
while(condition){ ... } - Simple for loop.
for(int i=0; i<10; ++i){ ... }
- Empty body loops should use “continue” or “{}”, but not single semicolon.
while(condition){} not while(condition);
2.6.5. Pointer and Reference Expressions
- When declaring a pointer variable or argument, you may place the asterisk adjacent to the variable name.
char *a; const string &str;
2.6.6. Preprocessor Directives and Macros
- Preprocessor directives are within the body of indented code or begin of the file; the directives should start at the beginning of the line.
- Macro names should name with all uppercase and underscores.
2.6.7. Class
- Any base class name should be on the same line as the subclass name, subject to the 80-column limit.
class MyClass : public OtherClass { ... ... };
- Type names (for classes, structs, typedefs, and enums) start with a capital letter and have a capital letter for each new word, with no underscores: MyExcitingClass.
- Constructor initializer lists can be all on one line or with subsequent lines if there are more things to initialize.
MyClass::MyClass(int var) : var_(var), var2_(var + 1) {} MyClass::MyClass(int var) : var_(var), var2_(var + 1), var3_(var + 2) {}
- The contents of namespaces are should not indented.
namespace { void foo() { ... ... } }
2.6.8. Horizontal Whitespace
- Keep white spaces both sides of operator like =, +, -, / , && according to the place it uses.
x = 0; x = -5; ++x; if (x && !y) v = w*x + y/z; v = w * (x + z);
- Keep space after each semicolon or colon exist before the line end.
for ( ; i < 5 ; ++i) for (auto x : counts) {)
2.6.9. Vertical Whitespace
- Do not waste new lines.
- Put one blank line between functions.
- Do not leave blank lines at the beginning or end of a function.
2.7. Other
- Use C++ casts like static_cast<>(). Do not use other cast formats like int y = (int)x; or int y = int(x);
- Use prefix form (++i) of the increment and decrements operators with iterators and other template objects.
- Use const whenever it makes sense and consider making data members const whenever they do not need to be modified after construction.
- Try not to use unsigned integers.
- Use 0 for integers, 0.0 for reals, NULL for pointers, and '\0' for chars when necessary.
- Use sizeof(variable) instead of sizeof(type) when you need to get the size of a variable.
- Each line of text in your code should be at most 80 characters long.
- Avoid the use of numeric values or hardcode values in code; use symbolic values instead.
- Do not allocate memory and expect that users will de-allocate it later.
3. Appendix -01
/******************************************************************* File: filename.ext Author: Author Name E-Mail: author@yourcompaney.com Description: Here is the area that should describe what is the usage of this class and what is the functionality of the class and the important things that need to mentions. Language: C++ Version: 1.0 Limitations: none/some (i.e: limitations such as file size string lengths etc..) Copyright: Your Companey Thread Safe: yes/no Extendable: yes/no Platform Depend:none/some (i.e.: Linux/Intel, Windows/Intel, Solaris/SPARC) Change History: -------------------------------------------------------------------- Date Author Description YYYY-MM-DD Author Name What is the improvement or change have done because of which reason *******************************************************************/
Referance
- The C++ Programming Language, By Bjarne Stroustrup
Publication Date: June 30, 1997 | ISBN-10: 0201327554 | ISBN-13: 978-0201889543 | Edition: 3 - C++ Coding Standards: 101 Rules, Guidelines, and Best Practices, By Herb Sutter and Andrei Alexandrescu
Publication Date: November 4, 2004 | ISBN-10: 0321113586 | ISBN-13: 978-0321113580 | Edition: 1 - http://cpp.capibara.com
- http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
- http://www.yolinux.com/TUTORIALS/LinuxTutorialC++CodingStyle.html
