• 09/13/99 06:53 PM
    Sign in to follow this  

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

    General and Gameplay Programming

    Myopic Rhino
    [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);
                    }


      Report Article
    Sign in to follow this  


    User Feedback

    Create an account or sign in to leave a review

    You need to be a member in order to leave a review

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

    There are no reviews to display.