Coolquest, Inc.	Home	Products	Support	About	Contact
C++BOLD Reference Manual

16.6. General Style Guidelines

The following guidelines were used to code the CBOLD framework and are recommended to CBOLD users.

Occasional deviations from the guidelines may improve readability.

Some of the guidelines below have rational motivations. Others just reflect personal preference.

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

Comments: Too many comments is better than too few. It is all too common to return to code after several months (or just a few days) and find you do not remember what the code was supposed to do or how it was supposed to do it.

Special comments: Some comments are intended for a particular audience, for example, for personnel performing PCB layout. By marking them with a special string, they can be found quickly with the IDE or with a command-line program such as grep. The string ">>>" is recommended for layout notes. For example:

class CM_MultiSwitch_Base : public TModule {
  ...
  CP_CDC_POS   CapI;        // input  cap, one per multiswitch   >>> place near TPS2033D
  CP_CDC_POS   CapO;        // output cap, one per multiswitch   >>> place near TPS2033D
  ...
};

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 and is fairly simple:

Good:

  if ( i > p ) {
    for ( j = 0... ) {
      Num = rand( Num );
    }
    if ( k != N )  return;
  }
  if ( l > m )  foo << 3;
  if ( j > 2 )  bar >> 4;

Bad:

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

Very Bad:

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

Spaces:
Consistent spacing is essential for readability as well as for efficient text searches.
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.,

"VCC5"  <<     PowerSupply_VCC.VIN   <<     CAP_VCC_I.POS;
"VCC5"  <<  PowerSupply_VCCINT.VIN   <<  CAP_VCCINT_I.POS;
"VCC5"  <<   PowerSupply_VCORE.VIN   <<   CAP_VCORE_I.POS;

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

CP_EMU_HEADER   EmuHeader;          // miscellaneous connectors
CP_JTAG_HEADER  SPROM_JTAG_Header;  // for serial configuration proms
CP_JTAG_HEADER  Module_JTAG_Header; // for FPGA's on DSP module
CP_HEADER10X2RT PowerHeader;        // Board runs off +5V only
CP_HEADER25X2   XGEN_Header0;       // some GEN's and EGEN's are routed

is more readable than this:

CP_EMU_HEADER EmuHeader;       // miscellaneous connectors
CP_JTAG_HEADER SPROM_JTAG_Header;  // for serial configuration proms
CP_JTAG_HEADER Module_JTAG_Header; // for FPGA's on DSP module
CP_HEADER10X2RT PowerHeader;      // Board runs off +5V only
CP_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 and standard abbreviations such as "DC" and "PLD" 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();

Capitalization is UpperCamelCase:
Capitalize each word in a name.
Avoid using underscores unless they improve readability.
Use an underscore to separate all-capital abbreviations from surrounding capital letters.

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

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

enum's: Use a few meaningful lowercase letters followed by a variable-like name, e.g.,

enum { ckRCLK = 1, ckSCLK = 2, ckNone = 4 };

Consistency: Consistency can help with readability, refactoring, etc.

For example, be careful and consistent when using the ^ operator. E.g., this:

VCC ^ Ferrite ^ "FILTERED_VCC";    // Connect VCC to Ferrite.A, "FILTERED_VCC" to Ferrite.B

produces different output from:

"FILTERED_VCC" ^ MyFerrite ^ VCC;  // Connect VCC to Ferrite.B, "FILTERED_VCC" to Ferrite.A

Though there is no harm electrically, because the ferrite is not polarized, being consistent will improve readability of output such as the symbolic netlist.

auto_reg: Even if you do not use the auto_reg Support Tool to register members, you should consider using // AR_BUS() comments for bus ports. Doing so will document the range of bus ports where they are declared, rather than in the Register() function, which can be many lines below the port declarations. It will also make your design more understandable to those who are accustomed to using auto_reg.