Date:     May 21, 2001
From:     Steve Pier
Subject:  ROD Style Guide


Here is a preliminary style guide for ROD C/C++ software. Some of the guide
is also applicable to Verilog code.

Below are guidelines, not necessarily rules. Some deviations are fine,
especially if they improve readability.

Some of the guidelines below have rational motivations. Others just reflect my
personal preference. In any case, we are better off if we all follow the same
guidelines. 


General:
  Use only spaces, not tabs -- this maintains text alignment regardless of the
system on which files are printed.

C++ builder note:  uncheck the "Use Tab Character" in the editor properties.
Spaces will be inserted when you press the tab key.

Comments:
  The DSP compiler is supposed to support end-of-line comments, so it is ok
  to use //.

  Too many comments is better than too few. It is all too common to return to
  code after several months (or several days) and find you don't remember
  how the code is supposed to work.

Indentation:
  Use two spaces per indent e.g.,
    void MyFunction() {
      for ( i = 0; i < 100; ++ i ) {
        Num = rand( Num );
      }
    }

Braces:
  Use braces even when they are unnecessary, unless the statement fits on a
single line:

Good:
  if ( i > p ) {
    for ( j = 0... ) {
      Num = rand( Num );
    }
    if ( k != N )  return;
  }

Bad:
  for ( i = 0; i < 100; ++ i )
    if ( L > 5 )
      while ( N == rand( 3 ) )
        k += 2;

Realy Bad:  
  for ( i = 0; i < 100; ++ i ) if ( L > 5 ) while ( N == rand( 3 ) ) k += 2;


Spaces:
  See code examples in this style guide.
  Use one space after left parenthesis and comma.
  Use one space before right parenthesis.
  Use no spaces between a function name and left parenthesis.

Alignment:
  Try to align code so that parallels can be seen, e.g.,

  conn( "VCC5",    PowerSupply_VCC.VIN ,    CAP_VCC_I.POS );
  conn( "VCC5", PowerSupply_VCCINT.VIN , CAP_VCCINT_I.POS );
  conn( "VCC5",  PowerSupply_VCORE.VIN ,  CAP_VCORE_I.POS );

Align blocks of end-of-line comments (within reason).

This:
  T__EMU_HEADER   EmuHeader;          // miscellaneous connectors
  T__JTAG_HEADER  SPROM_JTAG_Header;  // for serial configuration proms
  T__JTAG_HEADER  Module_JTAG_Header; // for FPGA's on DSP module
  T__HEADER10X2RT PowerHeader;        // Board runs off +5V only
  T__HEADER25X2   XGEN_Header0;       // some GEN's and EGEN's are routed

is more readable than this:
  T__EMU_HEADER EmuHeader;       // miscellaneous connectors
  T__JTAG_HEADER SPROM_JTAG_Header;  // for serial configuration proms
  T__JTAG_HEADER Module_JTAG_Header; // for FPGA's on DSP module
  T__HEADER10X2RT PowerHeader;      // Board runs off +5V only
  T__HEADER25X2 XGEN_Header0;   // some GEN's and EGEN's are routed



Function and variable naming convention:
  Function and variable names should be expressive but not awkward.
  Function and variable names should be concise, but they can be quite long
  if necessary. Avoid abbreviating words. (Acronyms are ok.) Tiny variable
  names, such as i, j, dx, can improve readability. Short names are preferred
  for variables or functions that are widely used, e.g., LogError();

  Follow the C++ Builder/Delphi naming convention:
    capitalize each word in a name
    avoid using underscores unless they help readability
    use an underscore to separate all-capital acronyms from
      surrounding capital letters

  But short variable names, especially, indexes in loops, should be lower case.

  MyVariable
  MyFIFO_Variable
  A_FIFO_Variable
  Variable1   // this is ok
  Variable_1  // this is ok if it seams more readable
  i           // short variable names--more readable if lower case
  dx
  

enum's:
  Use two or three lowercase letters followed by a variable-like name, e.g.,
    ckRCLK
    ckSCLK
    ckNone


That's all for now,

Steve