CS 242 Fall 2009 : Style Conventions

This page last changed on Aug 24, 2009 by cemeyer2.

Introduction

The following serves as a guideline to follow when writing your code for this class. There are many different styles of coding: this is simply one of them. While it is not neccessary to follow each of the guideline precisely, following these guidelines is often sufficient for style points in this class. To write code that is effective in industry, one must follow standard to maintain consistency of all written programs. Code style standards are necessary to maintain ease of understanding for humans. Even if someone has written very powerful code works very effectively, others need to understand it.

Naming Conventions

Clarity vs. Conciseness

Variables used only a few(i.e. 1-3) times in local context, don’t need to be very long.

Variables used in many places in different parts of the code should be descriptive and explain what the variable is doing.

Spelling

Eliminate all spelling mistakes in your code. Finding bugs because of misspelled variable names is a very common error and difficult to fix.

Ambiguity

Ambiguity in meaning

Two variable names that have very similar meaning become very confusing to the reader, and can cause bugs later on because the wrong variable name was used. For example, FileNum and FileIdx are two variable names that are used for different purposes, but could possibly be the source of confusion if one is accidently used in place of another.

Ambiguity in words

Avoid words that sound similar(homonyms) or are spelled the same as another word with similar meaning(

Ambiguity in letters

Be careful not to mix up the letter ‘l’ and the number ‘1’ . They can look very similar.

Keyword confusion

When a variable name contains keywords unique to the programming language, be sure to immediately rename it. While one usually might get a simple warning at first, it may cause other problems later on.

Loop variables

Loop variables can be descriptive too! Do not limit yourself to the standard i,j,k loop indexes. If you are iterating through a grid, row and column are excellent, descriptive names for loop iterators.

Data

Characters

Use ch to denote a character variable

Numbers

Use n to denote simple number variables.

Booleans

Use names that imply Truth or Falsehood. For example, use ‘is’ to describe variables that specify whether a process is complete. (e.g. isProcessComplete). Avoid negations in variable names (e.g. notDone).

Counters

Eliminate the use of ‘Num’. Instead, use ‘Count’ or ‘Index’.

Temporary variables

Eliminate uses of ‘temp’ in your code. Instead, name these variables based on their purpose. Consider the swap function(written in C-style), where instead of temp, we use xValue.

File Variables

Static Variables that correspond to specific files could be prefixed with an underscore. (e.g. _FileStaticVariable).

Functions

Begin function names with a lower case letter. Use camel case for long names. An example is : myFunctionName() .

Constants

Use all upper-case letters for contstants. If a constant is global, indicate so by preceding the name of the constant with ‘GLOBAL_’ .

Commenting

Avoid Comment Pollution

A polluted comment does not give the reader any more information about what is going on with the code than does the code itself. Such comment pollution should be avoided at all costs. The following shows an example of how comment pollution is meaningless to a reader, as well as how a “green comment” that actually tells the reader more information about the code and why it is written the way it is.

Polluted Comment
“Green” Comment
Statements

1. Eliminate extraneous comments that describe your personal emotions regarding the code.

2. Explain why this code statement is here, rather than how it works.

3. Eliminate abbreviations.

4. If a comment is elaborate or extremely detailed, warn the reader that this is so. For example, use /* */ for detailed comments, and // for simple comments.

5. “Hacks” (i.e. workaround) should be indicated clearly and justified.

Control Structures

1. indicate the end of a large code block (e.g. while , for, if) by endline comment. For example,

2. indicate units on data, if applicable

3. indicate ranges of input data, and use .. for series (e.g. “values one to n” would be specified as “1..n”)

4. state whether data is global or local

5. state whether data is input data(data_in or output data (data_out)

Document generated by Confluence on Feb 22, 2012 18:18

  1. No comments yet.

  1. No trackbacks yet.