CS 242 Fall 2011 : Style Conventions
CS 242 Fall 2011 : Style Conventions
This page last changed on Aug 08, 2011 by conadmin.
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.
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.
Eliminate all spelling mistakes in your code. Finding bugs because of misspelled variable names is a very common error and difficult to fix.
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.
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 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.
Use ch to denote a character variable
Use n to denote simple number variables.
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).
Eliminate the use of ‘Num’. Instead, use ‘Count’ or ‘Index’.
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.
Static Variables that correspond to specific files could be prefixed with an underscore. (e.g. _FileStaticVariable).
Begin function names with a lower case letter. Use camel case for long names. An example is : myFunctionName() .
Use all upper-case letters for contstants. If a constant is global, indicate so by preceding the name of the constant with ‘GLOBAL_’ .
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.
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.
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:09|