Source Code in Files Code Structure

Rule 1.Include files in C++ always have the file name extension .H.

Rule 2. Implementation files in C++ always have the file name extension .CPP.

Rule 3.Inline definition files always have the file name extension .INL.

Rec. 1.Inline functions should be implemented in include files instead of inline ones.

Rec. 2.Do not include the implementation of large classes into one large file. Divide it into many files.

Rec. 3.Divide long lines of code into a number of lines.

The purpose of these conventions is to provide a uniform interpretation of file names. One reason for this is that it is easier to make tools that base their behavior on the file name extension.

If a .CPP file contains a large number of function implementations, the object file produced by the compiler may be unnecessarily large. Moreover, the time taken to compile such a file may be too long.

Only old debuggers cannot debug inline functions. Hence, there are no needs to place inline functions in a separate file to debug them while testing the program.

It is impossible to read long lines of code without scrolling a window. To make your code more readable avoid using long lines of code.

Naming Files

Rule 4.File names must not contain spaces.

Rec. 4.Always give a file a name that is unique in as large a context as possible.

If a program has two files with the same name but in different subdirectories, there may be name collisions for files generated by the compiler.

Comments

Rule 5.All comments must be written in English.

Rule 6.Every file that contains source code must be documented with an introductory comment that provides information on the file name and contents.

Rule 7.All class declarations must be preceded by an introductory comment that provides information on the class parameters (for class templates), description, and prerequisites.

Rule 8.All function declarations must be preceded by comments specifying the function input/output and template parameters, return value, the exceptions the function may directly or indirectly throw, and its effect.

Exception 1:Overridden member functions of standard library classes (for instance, MFC classes) documented separately may be left uncommented.

Exception 2:If a function is implemented in the same place where it is declared and its body consists of no more than one statement, it may be left uncommented.

Rule 9.Each time the file is checked-in into a version control system for team development (for example, Visual SourceSafe) the file must be supplied with the comment that describes all modifications that were made.

Rule 10.All global and class member data must be documented. The comments should be placed, if possible, at the end of the declaration line.

Rule 11.The code that is left unfinished must be documented with an introductory ‘!!!’. Never use ‘!!!’ in other places.

Rec. 5.Use//for comments.

Examples 1-3illustrateRules 6-8.

It is necessary to document source code. Comments should be compact and easy to find. By properly choosing names for variables, functions and classes and by properly structuring the code, there is less need for comments within the code.

Note that comments in include files are mostly meant for the users of classes, while comments in implementation files are meant for those who maintain the classes.

It is helpful to use consistent style of documenting unfinished code in order to be able quickly find all such places. We recommend using ‘!!!’ because it attracts attention. See Example 4.

Comments are often said to be either strategicortactical. A strategic comment describes what a section of code is intended to do, and is placed before this code. A tactical comment describes what a single line of code is intended to do, and is placed, if possible, at the end of this line. Unfortunately, too many tactical comments can make code unreadable. For this reason, it is recommended to primarily use strategic comments, unless trying to explain very complicated code. SeeExample 5.

If the characters //are consistently used for writing comments, then the combination/* */may be used to make comments out of entire sections of code during the development and debugging phases. C++, however, does not allow comments to be nested using/* */.