Style Guide for CSIM Model Code

Most code will be written only once but read many times. Therefore, it is more important for programs to be easy to read without ambiguity, than to be easy to write with few keystrokes. -- Peter Coffee

Entity Naming

• Variables shall be lower case.
• Functions shall be lower case.
• Constants shall be upper case.
• Use enumerated types or defined macro names to represent cardinal values; not just numbers. This improves readability and maintainability by enabling systematic searches.
• Use short but descriptive name prefixes for identifiers declared in different modules, this avoids name clashes.
• Structure definitions should be uppercase for each first letter of a word and lower case for the rest.
• Use distinct, searchable, meaningful names.   Avoid usage of variable names such as i or a, which are difficult to search for, and which do not describe what they represent.
• Use underscores to distinguish distinct parts of names, such as bake_temperature

Code Structure

Indenting (ANSI)

• Indent one or two spaces per block nesting level.
• If one statement, then brackets ({}) are optional and can be on same line.
• If multiple statements in block, then place corresponding brackets in same column (I.E. line up vertically).
• If brackets are used, indent bracket one space, and contained code one or two additional spaces.

Spacing

• One blank line to separate variable declarations from executable code.
• Use one blank line to separate major sections of a routine.
• Use three (or more) blank lines to separate subroutine definitions.
• All variable assignments must have exactly one space between the assigned variable name and the equals sign. This improves readability and maintainability by enabling systematic searches for everywhere a variable's value is altered or set.
• Place a space before and after operators, including conditional, arithmetic, and logical operators. This improves readability, assists in searches, and sometimes avoids unintended syntax errors or bugs.
• No space needed before semi-colons.
• Use tabs where possible instead of spaces to reduce file size. Wrap lines longer than 120 columns for readability and hardcopy printability. (Tabs are modulo 8 spaces.)
• One space after every comma.
• One space before open parenthesis in, 'if', 'while', 'switch', and 'for' statements.
• No space before open parenthesis and function name in calls and defines.

Comments

Comment Types

• Boxed comments Use for section separators or prologs.
• Block comments Use at the beginning of each major section of the code as a narrative description of that portion of the code.
• Short comments Write on the same line as the code or data definition they describe.
• Inline comments Write at the same level of indentation as the code they describe.

Comment usage

• Use comments in the following:
  • a broad overview at the beginning of a module
  • data structure definitions
  • global variable definition
  • at the beginning of a function tricky steps within a function
• Each file must have a File Prolog.
• Subroutine Comments should have the following:
  • Purpose
  • Inputs
  • Outputs
• Tab comment over far enough to separate it from code statements.
• If more than one short comment appears in a block of code or data definition, start all of them at the same tab position and end all at the same position.

Statements

• Avoid pointer arithmetic.
• One statement per line.   (Preferred)
  (It is allowable to have two or more statements on a line, only when they are short and logically related. But separate them with multiple spaces.
  Example:
            x.r = 0;     x.i = 0;
  )
• Avoid assignments in conditional expressions.
• Avoid Goto statements.

Conditional Statements

• Avoid "? () :" statements. Use "if" instead.
• Place parenthesis around each part of condition expression for readability .

Security

• Avoid buffer overflow vulnerabilities. Use fgets instead of gets for keyboard and file input. Use bounded strcpy_safe instead of unbounded strcpy or strncpy. Set the maximum copy to be no larger than the buffer size. (strcpy_safe is preferred over strncpy, because strcpy_safe copies only up to the terminator character or the maximum buffer length, whichever is less. While strcpy_safe always fills to the maximum buffer length, which can create overflows when data is passed down to legacy routines. Also, strncpy would not terminate copied string with a null character if buffer length were exceeded. strcpy_safe ensures the copied string is terminated.) The strcpy_safe routine is included in all CSIM packages.

EXAMPLES

If one statement, then brackets ({}) are optional and can be on same line. Otherwise indent subordinate statement one space.

Example:           if   (x == y)   { q = r; }

Or:                     if   (x == y)   q = r;

Or:
                        if   (x == y)
                          q = r;
                        else
                          q = r;

If brackets are used, indent subordinate bracket one space, and contained code one or two additional spaces. (For consistency, block replaces single statement, and is therefore indented same as a single subordinate statement, as above.)   Line up corresponding closing bracket in same column as opening bracket, for easy matching of block begin, end pairs.

Example:

	if (pressure < bake_threshold1)
	 {
	  temperature = temperature + t_increment;
	  y = j + 5;
	 }
	else
	 {
	  temperature = temperature - t_increment;
	  y = j - 3;
	 }

For blocks containing many statements, and/or many subordinate nesting levels, label the opening and closing brackets with identical, meaningful comments . This supports matching corresponding begin, end brackets, both by eye and by search. Contained code can be lined up with bracket comments for clean look.

Example:

	while (x_speed  <  speed_limit)
	 { /*loop1*/
	   if (x_accel >= power_limit)
	    { /*slowdown*/
	      throttle = 0.5 * throttle;
	    } /*slowdown*/
	   else
	    { /*speedup*/
	      throttle = 1.25 * throttle;
	    } /*speedup*/
	 } /*loop1*/

Place parenthesis around each part of condition expression for readability.

Example:

	if ((x == y) && (g == k))

All variable assignments must have exactly one space between the assigned variable name and the equals sign.

Example:

	x = y;   // Not: x=y; or x= y;

Example:

	y = m * x + b;   // Not: y = m*x+y;

Boxed Comment Example

	/****************************************************
	* FILE NAME *
	* *
	* PURPOSE *
	* *
	*****************************************************/

Section Separator Examples

Major Separator

        /* ======================================================= */

        /* ******************************************************* */

	/*---------------------------------------------------------*/

Block Comment Example

	/*----------------------------------------------------------
	* Miscellaneous Info .
	* Block comments are used when there is more than one line.
	* Comments should be complete sentences.
	* Punctuation and capitalization improves readability.
	-----------------------------------------------------------*/

Short Comments Example

	/* Check if message is available */
	if (TOPOLOGY_TABLE[link_no].rq_len > 0)

Inline comments

	targ_phase = 2 * pi * rand( length(sigma), 1 );   /* Random target phases. */

File Prolog Example

	/********************************************************************
	* FILE NAME:
	*
	* PURPOSE:
	*
	* EXTERNAL VARIABLES:     (variables used)
	*
	* Compilation Instructions/Commands:
	*
	* Usage Instructions:	  (As appropriate)
	*
	* Author/Custodian: 	  (with organizational affiliation)
	*
	* History:
	*   Date   Version   Author   -   Brief Description of Change
	*
	*********************************************************************/