BOREALIS CODING STANDARDS

Nesime Tatbul, Don Carney, Bradley Berg

June 27, 2005

1. Introduction

This document contains basic C and C++ coding standards for the Borealis project with the intension of having an easily-readable and homogeneous-looking Borealis code-base. Borealis coding standards mostly inherit from Aurora coding standards. Hence, this document builds upon an earlier document prepared for Aurora by Don Carney [1].

2. File Names and File Organization

In general, use one file per class. A class file may contain related trivial classes. To avoid very large files it is reasonable to move some class methods to a separate file.

The file name should be the same as the class name (mixed case). The extensions are .h for C and C++ header files, .cc for C++ files, and .c for C files.

2.1 Namespaces

Declarations widely used in Borealis source code are declared in common.h. These include namespace definitions. We use a common namespace for Borealis. Your code should be enclosed between:

BOREALIS_NAMESPACE_BEGIN
           :
BOREALIS_NAMESPACE_END

The MEDUSA namespace was used in code inherited from the Medusa project. Over time legacy code should be converted to the BOREALIS namespace. Use the BOREALIS namespace in any new project code.

The NMSTL namespace is used within the threads library. NMSTL is the Networking, Messaging, Servers, and Threading Library for C++ written by Jon Salz [5]. It provides many nice features to facilitate developing code in C++, like class serializers, smart pointers, and macros for code debugging. As a general guideline, we should use this library, to the possible extent, for convenience in developing code in Borealis.

3. Coding Conventions

3.1 Symbolic Names

• Class names shall have the first letter of each word capitalized (e.g. SampleClass).

• Class methods and variables shall be lower case with an underscore between words (e.g. method\_variable).

• Class member variables shall also have a lead underscore (\_class\_variable). Do not use global variables! However, if you think need to, you must justify its use to at least two other people. If both of those people agree with the use of a global variable, follow the class variable standard for the global.

3.2 Source File Layout

• Public methods and variables shall be declared first; followed by protected; followed by privates. Note the location of "class", "public", "protected", and "private": they begin in the first column.

• Methods are listed first, then variables. Note the orientation of methods and variables. Their types line up (one tab in) and their names line up. Also note the declarations for pointers: The asterisk is contiguous with the name, not the type.

• Do not put executable code in header files unless it is part of a macro definition or a trivial get or set method.

3.3 Indentation and Spacing

While it is good to use tabs while editing, replace tabs with spaces when you save a file. Set your tab spacing to 4 spaces. Use tabs for indenting and for lining up names in class declarations. The code should look spiffy. If not, your tab settings are wrong. To test whether your using the right tab spacing, you can run this command:

    > pr -e4 -t file_name

Make sure that all tabs are replaced with spaces after you finish editing source files. Some editors automatically do this for you. Otherwise, you can use substitute commands. For example, if you are using a vi editor, you can simply do the following:

    :%s/<TAB>/<4-spaces>/g

Try to limit source code lines to a width of 80 columns. It is highly recommended to use a C/C++ Beautifier, such as bcpp [4]. bcpp indents C/C++ source programs, replacing tabs with spaces or the reverse.

3.4 Blocks of code

Put opening curly braces immediately below the first character of the previous line. Keep opening and closing braces aligned in the same columns. This makes it easy to visually match braces. All code within a pair of braces should be indented. Never code a block of code below a condition or loop construct (if, else, for, or do) without braces.

   if (condition)
       neverDoThis(argument);

If the conditional statement takes up only one line you may put the following statement on the same line as the left brace. Otherwise the following line should only contain the brace. By convention we will no put spaces after sets of left parenthesis or before sets of right parenthesis. It also helps to put a blank lines before and after any block of code.

   if (condition)
   {   doThis(argument);
         :
   }

   while ((compound condition)  &&
          (on multiple lines))
   {
       doThis();
         :
   }

   for (int i = 0; i < 10; i++)
   {
       ...
   }

   switch(condition)
   {
       ...
   }

3.5 Method Comment Boxes

Methods declarations should be enclosed in comment boxes. Unless there is a compelling reason, all variable declarations should be in the declaration section, not in the method body. For example, a variable may be declared in the body if a type has no default constructor (e.g. Status) or a declaration requires local scoping.

////////////////////////////////////////////////////////////////////////
//
//  A terse description of the method.
//
ResultType  test_method(// Description of the parameter.
                        ParameterType  parameter
                       )
{
    VariableType   variable;      // Description of the variable.
    ResultType     result;
//
//......................................................................

    some statements;

    return(result);
}

3.6 Header Files

• To avoid circular includes, all header files should begin with:

    #ifndef FILENAME_H
    #define FILENAME_H

And end with:

    #endif             // FILENAME_H

• Header files should use the portable base types (e.g. int32, single) declared in common.h. This will make the code much more portable.

• Avoid executable code in header files unless coding a trivial code body or defining a template.

• When including header files in your code, use double-quote (") for header files in the current directory, and '$<$' and '$>$' for header files in far off locations.

4. Commenting Conventions and Documentation

We use Doxygen [2] to automatically generate API documentation from source code comments. Doxygen can generate documentation in HTML/RFT/LaTeX format from code comments that follow certain conventions. Comments used to generate documentation are confined to header files. We have adapted one of the comment formats supported by Doxygen referred to as the JavaDoc style [3]. That is, single-line comments are introduced using three slashes, "///", and comment blocks use:

    /**
     * ... detailed description here ...
     */

Comments that are not part of the API documentation are intended for class developers. These comments shall use two slashes, "//", to introduce single-line comments and "/*" to introduce comment blocks or to comment out blocks of code. Note that this comment for should be used with private declarations as these do not get incorporated in the generated API documentation.

The quickest way to see how to comment header files is to look at the example file, SampleClass.h.

To run doxygen go to the borealis/src/doc/ directory in your sandbox and type:

borealis/src/doc> doxygen  doxygen.conf

You can add CVS log message pages to the pages generated by doxygen by starting the ssh-agent and running make from the borealis/src/doc/ directory.

5. Conclusion

A copy of this document is available in the Borealis CVS repository. Please email bb@cs.brown.edu for any comments about this document. Happy coding!

Bibliography

Developer Links