ICub File Organization Guidelines

The correct title of this article is iCub File Organization Guidelines. The initial letter is shown capitalized due to technical restrictions.

File Organization

In general, there are three different types of source code file in any given project. These are the interface, implementation, and application files.

In the case of projects coded using the C++ lanaguage, the interface file is a header file with the class declaration (with prototype method declarations but no method implementations) and templates.

The implementation file contains the source code for the implementation of each class method.

When using inline methods/functions, put the inline keyword in front of the method/function implementation but not in front of the prototype declaration in the interface file. Use inline methods/functions sparingly.

In the case of projects coded using the C language, the interface file is a header file that contains the function prototype declarations. The implementation file contains the source code of common functions that could be of general use. Such functions might eventually be placed in a library.

In both cases, the application file contains the source code for the particular project in hand. It #includes the interface file. The application file will contain, for example, the code for the graphic user interface and the main function.

File Structure

General Guidelines

Either three or four spaces should be used as the unit of indentation. Choose one standard and stick to it throughout the code.

Do not use tabs to indent text. If you are using Microsoft Visual C++ (Visual Studio) turn off the tabs option.

Avoid lines longer than 80 characters, since they are not handled well by many terminals and tools.

Add an empty line to the end of each file to keep the gcc compiler happy!

// empty line to make gcc happy

When an expression will not fit on a single line, break it according to the following general principles.

• Break after a comma.
• Break before an operator.
• Align the new line with the beginning of the expression at the same level on the previous line.

For example, consider the following statements.

  longName1 = longName2 * (longName3 + longName4 - longName5)
              + 4 * longName6;  // Good break

  longName1 = longName2 * (longName3 + longName4 
                           - longName5) + 4 * longName6;  // bad break: avoid

Declaration of External Functions

Declarations of external functions and functions to appear later in the source file should all go in one place near the beginning of the file (somewhere before the first function definition in the file), or else should go in a header file.

Do not put extern declarations inside functions.

Use of Guards for Header Files

Include files should protect against multiple inclusion through the use of macros that guard the file. Specifically, every include file should begin with the following:

#ifndef MYMODULE_H
#define MYMODULE_H

...  header file contents go here

#endif /* MYMODULE_H */