GENERIC

CODING STANDARDS

@(#)codestan.htm 3.4 08/26/02

Permission is granted to reproduce and adapt this document provided credit is given to the University of West Florida. This documentation is provided "as is" and no warranty of fitness for any particular purpose is made or implied.

NOTE: We are in the process of replacing these generic guidelines with more specific, language dependent coding standards. Standards for Java and Tcl/Tk have been written. When a standard for C/C++ is completed this document should be deleted from GUMP.

- - N. Wilde, August, 2002

ABSTRACT

This document is the Coding Guideline document for the generic maintenance process architecture for the University of West Florida. This document describes the basic conventions and coding guidelines to be used for the project. The scope is coding style and not functional organization. Coders should follow these conventions to the maximum extent possible in order to ensure a uniform appearance and improve maintainability.

PREFACE

This document is composed of four checklists that should be used by the programmer, the project coordinator, quality assurance, and anyone else who reviews the code for the project. These checklists are comprised of common ideas drawn from experts in the field, and are free from emotional ties to a particular coding style. The bibliography contains two references that provide the necessary fundamental and philosophical discussion about the finer points of code formatting.

Traditionally, many code standards have been quite dogmatic in their approach to code style. We did not wish to constrain anyone's creative abilities by imposing rigid standards on what is fundamentally a creative process: writing code. However, the guidelines presented in this document should provide the necessary guidance to produce code that has a consistent format and style to support readability and maintainability. No restriction on any construct offered by the language of choice (Ada or CJ) is stated or implied. If you can justify why you need to use a goto during code review, then by all means use it.

The only exception to this rule is in the unit and file headers. By standardizing these headers, the SE's will be able to understand the purpose of a given piece of code more easily. In addition, having a common header ensures that certain important items are documented. Appendices A-C contain the header format for units and files.

ABSTRACT
PREFACE
1.0 COMMENTING TECHNIQUE CHECKLIST
2.0 NAMING DATA CHECKLIST
3.0 LAYOUT CHECKLIST
4.0 SELF-DOCUMENTING CODE CHECKLIST
APPENDIX A, UNIT HEADER FORMAT, C CODE
APPENDIX B, UNIT HEADER FORMAT, ADA CODE
APPENDIX C, FILE HEADER FORMAT, C AND ADA CODE
REVISION HISTORY
BIBLIOGRAPHY

1.0 COMMENTING TECHNIQUE CHECKLIST

1.1 GENERAL

Does the source listing contain most of the information about the module?
Can someone pick up the code and immediately start to understand it?
Do comments explain the code's intent or summarize what the code does, rather than just repeating the code?
Has tricky code been rewritten rather than commented?
Are comments up to date?
Are comments clear and correct?
Does the commenting style allow comments to be easily modified?

1.2 STATEMENTS AND PARAGRAPHS

Does the code avoid endline comments?
Do comments focus on why rather than how?
Do comments prepare the reader for the code to follow?
Are surprises documented?
Have abbreviations been avoided?
Is the distinction between major and minor comments clear?
Is the code that works around an error or undocumented feature commented?

1.3 DATA DECLARATIONS

Are units on data declarations commented?
Are the ranges of values on numeric data commented?
Are coded meanings commented?
Are limitations on input data commented?
Are flags documented to the bit level?
Has each global variable been commented where it is declared?
Are magic numbers documented or, preferably, replaced with named constants or variables?

1.4 CONTROL STRUCTURES

Is each control statement commented?
Are the ends of long or complex control structures commented?

1.5 ROUTINES

Is the purpose of each routine commented?
Are other facts about each routine given in comments, when relevant, including input and output data, interface assumptions, limitations, error corrections, global effects, and sources of algorithms?

2.0 NAMING CONVENTION CHECKLIST

2.1 GENERAL NAMING CONSIDERATIONS

Does the name fully and accurately describe what the variable represents?
Does the name refer to the real-world problem rather than to the programming language solution?
Is the name long enough that you don't have to puzzle it out?

2.2 NAMING SPECIFIC KINDS OF DATA

Are loop index names meaningful (something other than i, j, or k if the loop is more than one or two lines long or is nested)?
Have all "temporary" variables been renamed to something more meaningful?
Are boolean variables named so that their meanings when they are True are clear?
Do enumerated-type names include a prefix or suffix that indicates the category - for example, Color for ColorRed, ColorGreen, ColorBlue, and so on?
Are named constants named for their abstract entities they represent rather than the numbers they refer to?

2.3 NAMING CONVENTIONS

Does the convention distinguish among local, module, and global data?
Does the convention distinguish among type names, named constants, enumerated types, and variables?
Does the convention identify input-only parameters to routines in languages that don't enforce them?
Is the convention as compatible as possible with standard conventions for the language?
Are names formatted for readability?

2.4 SHORT NAMES

Does the code use long names (unless it's necessary to use short ones)?
Does the code avoid abbreviations that save only one character?
Are all words abbreviated consistently?
Are the names pronounceable?
Are names that could be mispronounced avoided?

2.5 COMMON NAMING PROBLEMS: HAVE YOU AVOIDED...

...names that are misleading?
...names with similar meanings?
...names that are different by only one or two characters?
...names that sound similar?
...names intentionally misspelled to make them shorter?
...names that are commonly misspelled in English?
...names that conflict with standard library-routine names or with predefined variable names? Note: Overloading is permitted and sometimes encouraged in Ada.

3.0 LAYOUT CHECKLIST

3.1 GENERAL

Is formatting done primarily to illuminate the logical structure of the code?
Can the formatting scheme be used consistently?
Does the formatting scheme result in code that's easy to maintain?
Does the formatting scheme improve code readability?
Is the formatting consistent when viewed with a text editor in both UNIX and MS-DOS?
Have all tabs been eliminated?

3.2 CONTROL STRUCTURES

Does the code avoid double indented begin-end ({ }) pairs?
Are complicated expressions formatted for readability?
Are single-statement blocks formatted consistently?
Are case statements formatted in a way that's consistent with the formatting of other control structures?

3.3 INDIVIDUAL STATEMENTS

Are continuation lines indented sensibly?
Are groups of related statements aligned?
Are groups of unrelated statements unaligned?
Does each line contain at most one statement?
Is there at most one data declaration per line?

3.4 COMMENTS

Are the comments indented the same number of spaces as the code they comment?
Is the commenting style easy to maintain?

3.5 ROUTINES

Are the arguments to each routine formatted so that each argument is easy to read, modify, and comment?
In C, are new-style routine declarations used? (Compiler dependant)

3.6 FILES, MODULES, AND PROGRAMS

Does each file hold code for one and only one module?
Are routines within a file clearly separated with blank lines?
In Ada, avoid using the "use" clause which creates naming ambiguities.

4.0 SELF-DOCUMENTING CODE CHECKLIST

4.1 ROUTINES

Does each routine's name describe exactly what the routine does?
Does each routine perform one well-defined task?
Have all parts of each routine that would benefit from being put into their own routines been put into their own routines?
Is each routine's interface obvious and clear?

4.2 DATA ORGANIZATION

Are extra variables used for clarity when needed?
Are references to variables close together?
Are data structures simple so that they minimize complexity?
Is complicated data accessed through abstract access routines (abstract data types)?

4.3 CONTROL

Is the nominal path through the code clear?
Are related statements grouped together?
Have relatively independent groups of statements been packaged into their own routines?
Does the normal case follow the if rather than the else?
Are control structures simple so that they minimize complexity?
Does each loop perform one and only one function, as a well-defined routine would?
Is nesting minimized?
Have boolean expressions been simplified by using additional boolean variables, boolean functions, and decision tables?

4.4 DESIGN

Is the code straightforward, and does it avoid cleverness?
Are implementation details hidden as much as possible?
Is the program written in terms of the problem domain as much as possible rather than in terms of computer-science or programming language structures?

APPENDIX A (Unit Header Format, C code)

Unit(including main)

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

Module Name: The name of the unit being documented

Program: The name of the unit

Purpose: A detailed description explaining what the unit does and any
         particular reason why a certain design was chosen.

Inputs: A list of inputs (parameters) to the unit and their purpose

Outputs: A list of outputs generated by the unit and their purpose

Date Created: The date the unit was created

Modified: List of dates and reasons the unit was modified

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

APPENDIX B (Unit Header Format, Ada code)

Unit(including main)

--********************************************************

--Module Name: The name of the unit being documented

--Program: The name of the unit

--Purpose: A detailed description explaining what the unit does and any
--         particular reason why a certain design was chosen.

--Inputs: A list of inputs (parameters) to the unit and their purpose

--Outputs: A list of outputs generated by the unit and their purpose

--Date Created: The date the unit was created

--Modified: List of dates and reasons the unit was modified

--**********************************************************

APPENDIX C (File Header Format, C and Ada Code)

File Header

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

FILE: @(#) @(#)codestan.htm	3.4 - 08/26/02

PURPOSE: This file consists of all functions that provide and process
         the command line interface for the Recon3 instrumentor for C/C++.

SYSTEM: Recon3

HISTORY:
VER 	DATE    	AUTHOR		DESCRIPTION
1.0 	01 JAN 01	J. Smith	Created for T001 - Add r3 command
					line interface
==========================================================================*/
**********************************************************/

File Header Format, Ada Code

File Header

/==========================================================================

FILE: @(#) @(#)codestan.htm	3.4 - 08/26/02

PURPOSE: This file consists of all functions that provide and process
         the command line interface for the Recon3 instrumentor for C/C++.

SYSTEM: Recon3

HISTORY:
VER 	DATE    	AUTHOR		DESCRIPTION
1.0 	01 JAN 01	J. Smith	Created for T001 - Add r3 command
					line interface
==========================================================================*/
**********************************************************/

Field Descriptions (C and Ada)

FILE:  The name of the file and the SCCS keywords in this format.

PURPOSE: An overall description of why this file was created and what
         it does.

SYSTEM: The software product that this file is a component of.

VER:  This field is used to record the SCCS version number this file will
      have when you check it in.

DATE: The date the file was created in the form DD MMM YY.

AUTHOR:  This is the first initial and last name of the person making the change.

DESCRIPTION:  A brief explanation of why the file was created or modified.

REVISION HISTORY

BIBLIOGRAPHY

[MAGU93]

Steve Maguire, Writing Solid Code, Microsoft Press, Redmond, WA, 1993.

While not directly referenced in this document, this book is an excellent treatment of the techniques and mindset necessary to write "bug - free" C code. Recommended reading.

[MCCO93]

Steve McConnell, Code Complete, Microsoft Press, Redmond, WA, 1993.

Indispensable desktop reference. Complete user-level coverage of code standards and practices. Also discusses topics ranging from design and architecture to quality improvement. A worthwhile addition to your professional library.