January 23, 1996
Version 1.0
Files
Header files have a ".h" suffix. Header file contains class, struct, and union declarations, enum declarations, #defines, typedefs.
Implementation files have a ".cc" (UNIX) or ".cpp" (Windows, DOS) suffix. Implementation files contain function and method implementations.
Make a header block in header files and source code files. The header should contain title, author, date, and project information as well as a simple description of how the file fits into the project.
Names of Things
Names of Common C++ Characters
{ | open brace, open curly |
} | close brace, close curly |
( | open parenthesis, open paren |
) | close parenthesis, close paren |
[ | open bracket |
] | close bracket |
. | period, dot |
! | exclamation point, bang, not |
| | bar, vertical-bar, or, or-bar (actually a "vertical virgule") |
& | ampersand, and, reference, ref |
* | asterisk, multiply, star, pointer |
/ | slash, divide |
// | slash-slash, comment |
# | pound |
/ | backslash, (sometimes "escape") |
~ | tilde |
The primitive type name "char" is usually pronounced like the first syllable of "charcoal." Sometimes it is pronounced like "care" and sometimes "car."
Names and Indentation
Names of Naming Conventions
- interspersed_underscores lowercaseMixedCapital CapitalMixedCapital ALL_UPPERCASE
Applications of Naming Conventions
- enumeration_item_name
- variableName
- TypeName, ClassName, MethodName()
- UnixFileName.cc
- dosfn.cpp
- POUND_DEFINES
Self-documenting Code
- Use long names for every name in your program.
No Magic Numbers
- Numeric constants besides 0 (and sometimes 1) are not allowed. Use constants or #defines.
Whitespace
- Space (what you get when you press spacebar)
- Newline (what you get when you press enter)
- Tab (substitutes for 8 spaces)
Space and Indentation
- After an open brace, indent every subsequent line four spaces until the matching close brace.
- If an if, while, or for has no brace following, indent the next line two spaces.
- Indent lines which end in a colon backward two spaces (public, case).
- A space precedes and follows reserved words (if, else, class, struct) unless preceded or followed by indentation or newlines or special punctuation.
- A space precedes and follows operators and comparators (except unary operator bang is not followed by a space).
- Pointer variants (ampersand, star) are preceded and followed by space in declarations.
- Pointer variants (ampersand, star) are preceded (but not followed) by a space in expressions.
- A space follows an open parenthesis.
Newline
- Newline precedes an open brace in the following: class, struct, union, enum, method, function (but not: if, else, do, for, while, switch --- these braces are preceded by a single space.)
- Newline follows a close brace for method, function, if, else, do, for, while, switch.
- Semi-colon, then newline, then blank line after close brace for class, struct, union.
- Newline follows an open brace.
Comments
- Comments always begin at current indentation level with "//" and a space.
- No other construct may appear on the same line as a comment.
- Comments always preceed the construct they address.
- Use complete sentences in a comment.
- When describing a statement, comments may be in the imperative.
Above all, be guided by what pleases the eye. Be guided by what makes your code MORE READABLE.
Header File Example
// MODULE NAME: ClassName.h // PROJECT: CS1344-1,2 Course Notes // AUTHOR: Neill Kipp // DATE: January 1, 1996 // DESCRIPTION: This file presents examples of naming and // indentation style in a C++ class declaration. This title // information is minimal. // The following prevents files from being included // twice. It is a naming exception designed to emulate a file name // (period is not a name character; underscore is). #ifndef ClassName_h #define ClassName_h // This directive includes the superclass declaration. #include "super.h" // This directive includes another class declaration. #include "other.h" // The comment for an enumeration declaration precedes the declaration. enum OverflowState { // Each item's comment precedes it at the same indentation as the item. no_overflow, // Follow the last item with a comma; // it helps avoid syntax errors when adding or rearranging items. overflow_occurred, }; // This class shows how naming conventions and comments are used in a // simple class declaration. Whitespace precedes and follows reserved // words (like "public"). class ClassName { // After a brace, indent four spaces. // The description of the variable "memberData" goes here. int memberData; // If a line ends in single colon, reverse-indent two spaces. public: // The constructor gives initial values to member data. ClassName(); // The destructor guarantees clean deallocation. // The tilde (~) is part of the method name. It is not an operator. ~ClassName(); // This method increments the member variable by the value in "howMuch" // and returns TRUE if overflow is detected (FALSE otherwise). Method // comments tell what the method does, what the arguments are, // and what the method returns. OverflowState IncrementMemberVariable( int howMuch); // Prints message about overflow. void ShowOverflow( OverflowState overflow); }; #endif
Source code file example
// MODULE NAME: ClassName.cc // PROJECT: CS1344-1,2 Course Notes // AUTHOR: Neill Kipp // DATE: January 1, 1996 // DESCRIPTION: This file presents examples of naming and // indentation style in a C++ class implementation. This title // information is minimal. // This directive includes header information for the "ClassName" class. #include "ClassName.h" ClassName:: ClassName() { // Initialize member data (statement comments are in the imperative, // and preceed the statement). Suggestion: write the comments first, then // write the code. memberData = 0; } // The return type appears on the first line, // followed by the class name colon-colon on the second, // and finally the method name on the last. Then a newline, an open brace // and then indent. Notice the space after the open parenthesis. It helps // the eye catch the type name. OverflowState ClassName:: IncrementMemberVariable( int howMuch) { // Check the overflow condition. if ( TOO_BIG - memberVariable > howMuch) { // If overflow, return that overflow occurred. return overflow_occurred; } else { // Otherwise, return overflow is ok. return overflow_none; } } // This code implements the ShowOverflow method. void ClassName:: ShowOverflow( OverflowState overflow) { // Switch is a reserved word. It is followed by a space. switch ( overflow) { // Lines ending in a colon reverse indent two spaces. case no_overflow: // Display message about no overflow. cout << "No overflow occurred./n"; break; case overflow_occurred: // Display message that overflow occurred. cout << "Warning: overflow occurred./n"; break; } }
Other examples
// Note the spacing and indentation in the for statement. for ( whichItem = 0; whichItem < BIG_NUMBER; whichItem++) { DoSomething( whichItem); } // Bang is not followed by a space. while ( !SemaphoreOK()) { DoWaitForSemaphore( LONG_TIME);