Basic Programming Style Elements for CSC209

Appropriate Use of Comments

• Introduce each function/subroutine plus its parameters: this way someone reading your code can understand how each function is to be used without having to read the function's code explicitly.
• A good starting point for documentation of functions included in a library.
• Allows you to make explicit assumptions like "this function assumes the elements in the array are sorted before calling this function"

 
• Detail the basic steps in your alorithm: Most functions can be thought of as implementing a number of logical steps, where each step involves multiple lines of code: a simple comment naming each step is useful. For example:
 
/* open file  */
/* move to record */
/* compute new salary */
/* update record */
/* close file */
• Whenever something isn't obvious: You don't need to comment every line of code, but if something is not immediately obvious, it deserves a comment.

 
• Not overdone: You don't need a comment for every line of code! Keep your comments concise, clear and use only when needed.

 
• Comment as you go, not at the end: If you do it as you go, then it's done. If you don't, you may spend extra time remembering why you did what you did. (Note: I receive many assignments with no comments, then the student says "I sent the wrong one, can I resubmit it" ... the answer is "no.")

Appropriate Use of assert() Statements

An assert() statement allows you to directly encode assumptions you make. For example, if char *p is a parameter to a function, and you have assumed that the function is never called with a NULL value for p, then use the statement

at the start of the function. These statements are useful for debugging your code, as they quickly identify when an assumption has been violated.  Most compilers remove assert() statements automatically when a final, "release" version of the code is being compiled, so they do not have an adverse affect on performance.

Some Do's and Don'ts for assert()

Don't use assert() in place of required error checking. For example:

FILE *fp ;
fp = fopen("somefile","rw");
assert(fp != (FILE *)NULL);

Since files routinely cannot be opened (the file is missing, or the user doesn't have the required permission to open the file), you should instead use an 'if' statement to check if fp is NULL, and warn the user if it is. You don't want the program to terminate just because a file wasn't found!
 

Don't write assert statements with "side effects". For example

assert(i++ == n);

is problematic ... the program behaves differently in "release" versions, because the assert() statements are removed and i never gets incremented!
 

Use assert() before accessing a variable about which you are making an assumption (I can't tell you how many times I've seen something like

*p = 5 ;
assert(p != (int *)NULL);
 

If p is NULL, this will die with a seg fault error before the assert() statement catches the error)

Use of Variable Names

• Choose variable names that are meaningful: For example, the variable name "totalCost" makes a program much easier to understand than if the variable had been named "x"!
• Don't skimp by using only short variable names: Sure "x" is easier to type, but "totalCost" is better. Good variable names are often 10-20 characters in length!
• You may wish to use a naming convention where all integer variables have names beginning with "n", all long integer variables have names starting with "nl", all float variable names start with "f", all boolean variables have names starting with "b" etc. This way someone reading your code can easily ascertain a variable's type. One example of this is 'Hungarian Notation'. For more info on Hungarian Notation, type "Hungarian Notation" into any

Internet search engine, or check the reference below.

Use of Global Variables

• Don't unless it is absolutely necessary (i.e. it is impossible to write the program without them).
• In CSC209, you will lose style marks for use of global variables when not absolutely necessary.

Use of White Space

• Use indenting to indicate scope: For example, every time you write a for loop, indent all the statements inside the loop by two spaces each so that at a glance you can see which lines are code are part of the loop and which aren't.

 
• Align things vertically: I like to align operators such as "=" one above the other, purely for readability.

 
• Leave a blank line between separate steps in an algorithm: (E.g. you might leave a blank line between the code for /* open file */ and /* move to record */ in the example mentioned above.)

Breaking Code Into Functions

While there are not hard and fast rules about when to take a section of code an move it into a separate function, the following quidelines might help:

• If you find you are re-using the same lines of code over and over again, make it into a function.
• If you think you might re-use a section of code in a different context, make it into a function.
• Use functions to keep together lines of code that logically belong together.
• Don't break code into separate functions just because it exceeded some preset number of lines; keep lines of code that logically belong together together!

Casting Pointers

This section applies mostly to C/C++.

• Cast the return value from malloc() to the type of pointer you want it to be. This allows a reader of your program to know what type of pointer is in use without having to look up the declaration of the variable.
• When comparing a pointer to an integer value, be sure to cast the integer to the correct pointer type. This especially important when comparing a pointer to a negative integer value, such as -1. For example:


if (p == (Sighandler *)-1)
if (p != (int *)NULL)

References

• "Code Complete" by Steve McConnell, Microsoft Press, 1993
• "Rapid Development" by Steve McConnell, Microsoft Press, 1996
• Charles Simonyi and Martin Heller, "The Hungarian Revolution", BYTE, Aug. 1991 (vol. 16, no. 8)