[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 Coding Style

For consistency and ease of future maintenance, when working on Crystal Space source code, please follow the following guidelines. Also be sure to read important portability guidelines presented in the Portability section. See section 9.2 Portability.

  1. Indentation

    Indent with two (2) spaces. If you use tabs then they must be interpreted as eight (8) spaces. This means that you should not use the tab character for indentation since that would indent by eight characters rather than two. Also consider avoiding tabs altogether in order to eliminate tab-related problems. Here is an example of proper indentation:

     
    void foo()
    {
      int a;
      for (a = 0; a < 10; a++)
      {
        int b = bar();
        if (a < b)
          printf("Hello\n");
      }
    }
    

    This example also illustrates how to place curly braces and where to add spaces, for example `for_(' rather than `for(_', where `_' represents whitespace in this context. Also add sufficient whitespace between tokens.

  2. Class and Method Naming

    Classes should be named in this fashion: csThisIsAClass. The name starts with lower-case `cs' and has every word capitalized.

    Methods and functions should be named in this fashion: ThisIsAMethod(). Each word in the name is capitalized.

  3. SCF Interfaces

    SCF interfaces always start with a lower `i', as in iThisIsAnInterface. See section 6.3 Shared Class Facility (SCF).

  4. Doxygen and Comments

    Use Doxygen comments in header files to document classes, methods, and functions. These comments are extracted with the Doxygen tool and HTML documentation is generated from them.

    Warning: Always use Doxygen comments for a class. If you fail to do so then Doxygen will ignore comments for methods within the class itself.

    A one line Doxygen comment uses three slashes (`///') rather than two as is typical for normal C++ comments. Multi-line Doxygen comments are specified with `/** ... */' rather than `/* ... */'. Here is an example:

     
    /**
     * This class represents a blue ball.
     * Blue balls bounce higher than red balls.
     */
    class csBlueBall
    {
    private:
      // A private function, so no Doxygen comment here,
      // but still commented for readers of the header file.
      void PrivateFunction();
    
    public:
      /// This is the constructor which initializes the blue ball.
      csBlueBall();
    
      /**
       * This is a multi-line comment.
       * And this is the second line of the multi-line comment.
       */
      void Deflate();
    };
    

  5. Maximum Line Length

    In general, lines in source code should be no longer than 78 characters. This facilitates generation of hard-copy and works better with certain tools which process code or text files.

  6. Multiple-Inclusion Protection for Headers

    Be certain to insert multiple-inclusion protection in all header files. These controls should take this form:

     
    #ifndef __CS_FILENAME_H__
    #define __CS_FILENAME_H__
    ...
    #endif // __CS_FILENAME_H__
    

  7. Include `cssysdef.h'

    Always include `cssysdef.h' in each source file as the very first file included. If you need to use special facilities provided by `cssysdef.h' then be sure to #define the appropriate macro before including `cssysdef.h'.

    Never include `cssysdef.h' in header files.

  8. Module and Library Dependencies

    Do not introduce unnecessary dependencies between libraries and modules. Absolutely avoid introducing circular dependencies.

    For instance, code in the csGeom library should never refer to code from the csEngine library. The other way around is okay, however, since csEngine is at a higher level within the dependency hierarchy.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html