Style Guide for CSIM Model Code

Style Guide for CSIM Model Code

This document provides recommendations and guidelines for writing C-Code that is easy to read, understand, and maintain.
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

Code Structure

Indenting (ANSI)

Spacing

Comments

Comment Types

Comment usage

Statements

Conditional Statements

Security

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))
Spacing Example

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;
Place a space before and after operators, including conditional, arithmetic, and logical operators.

Example:

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

Boxed Comment Example


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

Section Separator Examples

Major Separator


        /* ======================================================= */
Medium Separator

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