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.
[size="5"] 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")&ersand, and, reference, ref*asterisk, multiply, star, pointer/slash, divide//slash-slash, comment#pound\backslash, (sometimes "escape")~tilde
[size="5"] Names and Indentation
[size="3"] Names of Naming Conventions
- interspersed_underscores
- lowercaseMixedCapital
- CapitalMixedCapital
- ALL_UPPERCASE
- enumeration_item_name
- variableName
- TypeName, ClassName, MethodName()
- UnixFileName.cc
- dosfn.cpp
- POUND_DEFINES
- Use long names for every name in your program.
- Numeric constants besides 0 (and sometimes 1) are not allowed. Use constants or #defines.
- Space (what you get when you press spacebar)
- Newline (what you get when you press enter)
- Tab (substitutes for 8 spaces)
- 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 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 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.
[size="5"] 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// 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;
}
}// 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);
}
regarding lowercaseMixedCapital and CapitalMixedCapital, there's already a name for them:
mixedCapital
CamelCase (I guess because of the O'Camel language)
Regarding self documenting code, there are only 2 rules
- write code that is easy to understand what it do
- comment only when needed
I'll avoid to "use long names". first of all "USE RIGHT NAMES": some names will be long, some others will be short. If possible never use defines (neither for constants!, maybe a static member variable is better scoped ?). Defines should do only pre-compiler magic. (import export macro, header guards.. if you start using defines for different stuff consider some alternative way to solve your problem.. if possible).
Also I tend to move all "copyright/author" stuff at the end of files. When I want to program I usually want to see immediatly the class, not who did it. If later the class have some trouble then I'll look who did it.