ICub Software Standards

From Wiki for iCub and Friends
Jump to: navigation, search
The correct title of this article is iCub Software Standards. The initial letter is shown capitalized due to technical restrictions.

File Organization Standards

File Organization: Interface, Implementation, and Application Files

Split your code into (at least) three files:

  1. the interface file, a myModule.h header file with the class declarations and prototype method declarations
  2. the implementation file, a myModule.cpp source code file with the method definitions.
  3. the application file, a myModuleMain.cpp source code file with the class instantiations; it #includes the interface file and typically contains the main function.


The implementation and application files, myModule.cpp and myModuleMain.cpp should be placed in the $ICUB_ROOT/src/myModule directory.


The interface file, myModule.h, should be placed in the $ICUB_ROOT/src/myModule/include/iCub directory.

File Structure

Indentation

  • 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.


Last Line is Blank

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


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 */


Documentation Standards

Introduction

Programs should have two kinds of comments: implementation comments and documentation comments.


Implementation comments are those which explain or clarify some aspect of the code. They are delimited by /* ... */ and //.


Documentation comments are intended to be extracted automatically by the Doxygen tool to create either HTML or LaTeX documentation for the program. They are delimited by /** ... */. Documentation comments are meant to describe the specification of the code from an implementation-free perspective. They are intended to be read by developers who won't necessarily have the source code at hand. Thus, documentation comments should help a developer understand the usage of the program, rather than its implementation.


All comments should be written in English.

Implementation Comments

Programs can have four styles of implementation comments:

 /*
  * Here is a block comment. 
  */
 /* Single-line comments */
 return general_answer(a);    /* training comments */
 // end-of-line comments


The first implementation block comment in every file should be the copyright and licence notice. Cut and paste the comment block below, inserting the year, name of author, and email address.

/* 
 * Copyright (C) <year> RobotCub Consortium, European Commission FP6 Project IST-004370
 * Author <name of author>
 * email:   <firstname.secondname>@robotcub.org
 * website: www.robotcub.org
 * Permission is granted to copy, distribute, and/or modify this program
 * under the terms of the GNU General Public License, version 2 or any
 * later version published by the Free Software Foundation.
 *
 * A copy of the license can be found at
 * http://www.robotcub.org/icub/license/gpl.txt
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License for more details
*/

The comment should be placed at or close to the beginning of the file.

Documentation Comments

Documentation comments describe classes, constructors, destructors, methods, members, and functions.


The Doxygen documentation system is used to extract the documentation comments and create external documentation in HTML or LaTeX.


Each documentation comment is set inside the comment delimiters /** ... */. Within this comment, several keywords are used to flag specific types of information (e.g. @param, @see, and @return).


Documentation comments are placed in front of a declaration or definition.


The #include file for an iCub module (i.e. the interface file) should have an implementation block comment which provides a clear summary of the function and usage of that module, as follows.

/** 
 * @ingroup icub_module
 *
 * \defgroup icub_<moduleName> <moduleName>
 *
 * detailed description of the module goes here ....
 *
 *
 * \section lib_sec Libraries
 *
 * YARP.
 *
 * \section parameters_sec Parameters
 * 
 * Command-line Parameters
 * 
 * The following key-value pairs can be specified as command-line parameters by prefixing -- to the key 
 * (e.g. --from file.ini. The value part can be changed to suit your needs; the default values are shown below. 
 *
 * - <key> <value>           
 *   <description>
 *
 * - ...
 *
 *
 * Configuration File Parameters
 *
 * The following key-value pairs can be specified as parameters in the configuration file 
 * (they can also be specified as command-line parameters if you so wish). 
 * The value part can be changed to suit your needs; the default values are shown below. 
 *   
 * - <key> <value>           
 *   <description> 
 *
 * - ... 
 *
 * 
 * \section portsa_sec Ports Accessed
 * 
 * - <portName>              
 *   <description>
 * 
 * - ...
 *                      
 * \section portsc_sec Ports Created
 *
 *  Input ports
 *
 *  - <portName>
 *    <description>
 *
 *  - ...
 *
 * Output ports
 *
 *  - <portName>
 *    <description>
 * 
 *  - ...
 *
 * Port types 
 *
 * The functional specification only names the ports to be used to communicate with the module 
 * but doesn't say anything about the data transmitted on the ports. This is defined by the following code. 
 *
 * - <portType>   <portName>        
 *
 *
 * \section in_files_sec Input Data Files
 *
 *  - <fileName>
 *    <description>
 *
 * \section out_data_sec Output Data Files
 *
 *  - <fileName>
 *    <description>
 *
 * \section conf_file_sec Configuration Files
 *
 *  - <fileName>
 *    <description>
 * 
 * \section tested_os_sec Tested OS
 *
 * Linux and Windows
 *
 * \section example_sec Example Instantiation of the Module
 * 
 * <moduleName> <parameter list>
 *
 * \author <Your Name>
 * 
 * Copyright (C) <year> RobotCub Consortium
 * 
 * CopyPolicy: Released under the terms of the GNU GPL v2.0.
 * 
 * This file can be edited at src/<moduleName>/src/<moduleName.h>.
 * 
 **/

Coding Standards

Console Messages

All console messages should identify the module from which they come, like this:

moduleName: error message

This can be effected in the following way

cout << getName() << ": error message" << endl;

Naming: C++ Language Conventions

The following are the naming conventions for identifiers when using C++.


Identifier Type   Rules for Naming                                    Examples  
                         
Classes           Class names should be nouns, in mixed case with     class ImageDisplay                 
                  the first letter of each internal word capitalized  class MotorController              
                                                                                                                
Methods           Method names should be verbs, in mixed case with    int grabImage()                    
                  the first letter in lowercase, with the first       int setVelocity()                  
                  letter of each internal word capitalized                                                      
                                                                                                                
Variables         variable names should be in mixed case with the     int    i;                 
                  first letter in lowercase, with the first letter    float  f;                 
                  of each internal word capitalized                   double pixelValue;        
                                                                                                                
Constants         The names of variables declared as constants        const int WIDTH = 4;      
                  should be all uppercase with words separated by                                               
                  underscores _                                                                 
                                                                                                                
Type Names        Typedef names should use the same naming policy as  typedef uint16 ModuleType 
                  that used for class names                                                                     
                                                                                                               
Enum Names        Enum names should use the same naming policy as     enum PinState {           
                  that used for class names.                             PIN_OFF,               
                  Enum labels should should be all uppercase with        PIN_ON                 
                  words separated by underscores _                    };

Naming: C Language Conventions

The following are the naming conventions for identifiers when using C.

Identifier Type   Rules for Naming                                    Examples  
 
Functions         Function names should be all lowercase with words   int  display_image()      
                  separated by underscores _                          void set_motor_control()  
                                                                                                            
Variables         variable names should be all lowercase with words   int    i;                 
                  separated by underscores _                          float  f;                 
                  of each internal word capitalized                   double pixel_value;       
                                                                                                            
Constants         Constants should be all uppercase with words        #define WIDTH 4           
                  separated by underscores _                                                  
                                                                                                            
#define           #define and macro names should all uppercase        #define SUB(a,b) ( (a) - (b) )    
and Macros        with words separated by underscores _