Elements of Programming Style -- The C++ Style Guide

Published September 13, 1999 by Neill Kipp, posted by Myopic Rhino
Do you see issues with this article? Let us know.
Advertisement
[size="5"]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.

[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")&ampersand, 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[size="3"]Applications of Naming Conventions
    • enumeration_item_name
    • variableName
    • TypeName, ClassName, MethodName()
    • UnixFileName.cc
    • dosfn.cpp
    • POUND_DEFINES[size="3"] Self-documenting Code
      • Use long names for every name in your program.[size="3"] No Magic Numbers
        • Numeric constants besides 0 (and sometimes 1) are not allowed. Use constants or #defines.[size="3"] Whitespace
          • Space (what you get when you press spacebar)
          • Newline (what you get when you press enter)
          • Tab (substitutes for 8 spaces)[size="3"] 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.[size="3"] 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.[size="3"] 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.

                  [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
                  [size="5"] 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;
                  }
                  }

                  [size="5"] 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);
                  }
Cancel Save
0 Likes 1 Comments

Comments

Dario Oliveri

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.

August 07, 2013 03:05 PM
You must log in to join the conversation.
Don't have a GameDev.net account? Sign up!
Advertisement