[FrontPage] [TitleIndex] [WordIndex

Note: You are looking at a static copy of the former PineWiki site, used for class notes by James Aspnes from 2003 to 2012. Many mathematical formulas are broken, and there are likely to be other bugs as well. These will most likely not be fixed. You may be able to find more up-to-date versions of some of these notes at http://www.cs.yale.edu/homes/aspnes/#classes.

Because C imposes few restrictions on how you write a program, it is up to the programmer to format and structure code in a style that will be readable by other programmers. Many programming shops have explicit in-house style guides that are enforced on their programmers; but even in the absence of explicit rules, it is worth adopting a clear and consistent style to avoid confusing later programmers (including yourself after you have forgotten why you wrote your code the way you did).

1. Formatting

The goal of good programming style is that anyone reading a fragment of your code should be able to intuit what the code is doing without having to parse detailed bits of it our look up anything else anywhere else. This means that

   1 /* Prints numbers from n to 0 and back to n again */
   2 void
   3 countDownAndUp(int n)
   4 {
   5     int i;
   6 
   7     for(i = n; i >= 0; i--) {
   8         printf("%d\n", i);
   9     }
  10 
  11     for(i = 1; i <= n; i++) {
  12         printf("%d\n", i);
  13     }
  14 }

2. Structure

By "structure" we mean the choices of how to organize your computation into functions, how to pass information between the functions, how to store it, etc. There are usually many choices of how to do this: at one (almost always bad) extreme, one can put an entire program in a single giant main function and have every variable be a global variable. However, it is better to break up a program into small, manageable chunks, since (a) other programmers will be able to understand what each small piece is doing, (b) you can test the small pieces individually, and (c) you may be able to reuse components in other contexts. Some principles of program structure are:

For fanatically high-performance code, it may be necessary to violate some of these principles (but maybe not: the cost of calling a simple function can often be optimized away by a smart enough compiler). But this should be done only in cases of dire need, only on the parts of the code that are actually time-critical, and with scrupulous documentation of why you are doing it. Never forget that premature optimization is the root of all evil.

3. Details

Below are some more detailed guidelines that I wrote for the 2002 version of CS223.

This is a partial list of rules of thumb for good programming style in C. These will be used as the basis of style grading for homework assignments, though we reserve the right to penalize egregiously awful code even if it follows all of the principles in this document. More rules may be added as the semester goes on and we notice more things we don't like, so it is worth looking at the on-line version of this document from time to time. A more comprehensive and general overview of the issues of programming style in C can be found on Chapter 1 of Kernighan and Pike.

3.1. Compilation and behavior

These are rules that are enforced explicitly or implicitly by the automated test scripts.

3.2. Comments

3.3. Naming

A general naming rule of thumb: if you can look at any five-line section of your code and be able to make a reasonably good guess about what it does without having to look at anything else, your names are good enough.

3.4. Whitespace

3.5. Macros

   1 #define FOLLOWING_THING (THING+1)
   2 

   1 #define NUM_SUITS (4)                      /* number of suits in the deck */
   2 #define NUM_RANKS (13)                     /* number of ranks in each suit */
   3 #define NUM_CARDS (NUM_SUITS * NUM_RANKS)  /* total number of cards */
   4 

   1 #define ArrayRef(a,row,col) ((a)->data[(row)*(a)->num_cols+(col)])
   2 

3.6. Global variables

3.7. Functions

3.8. Code organization

4. Style checklist

Below is the style checklist used for style grading in CS223. Note that it includes the option to remove points for particularly ugly code not covered by specific guidelines

Style grading checklist
Score is 20 points minus 1 for each box checked (but never less than 0)

Comments

[ ] Undocumented module.
[ ] Undocumented function other than main.
[ ] Underdocumented function: return value or args not described.
[ ] Undocumented program input and output (when main is provided).
[ ] Undocumented struct or union components.
[ ] Undocumented #define.
[ ] Failure to cite code taken from other sources.
[ ] Insufficient comments.
[ ] Excessive comments.

Naming

[ ] Meaningless function name.
[ ] Confusing variable name.
[ ] Inconsistent variable naming style (UgLyName, ugly_name, NAME___UGLY_1).
[ ] Inconsistent use of capitalization to distinguish constants.

Whitespace

[ ] Inconsistent or misleading indentation.
[ ] Spaces not used or used misleadingly to break up complicated expressions.
[ ] Blank lines not used or used misleadingly to break up long function bodies.

Macros

[ ] Non-trivial constant with no symbolic name.
[ ] Failure to parenthesize expression in macro definition.
[ ] Dependent constant not written as expression of earlier constant.
[ ] Underdocumented parameterized macro.

Global variables

[ ] Inappropriate use of a global variable.

Functions

[ ] Kitchen-sink function that performs multiple unrelated tasks.
[ ] Non-void function that returns no useful value.
[ ] Function with too many arguments.

Code organization

[ ] Lack of modularity.
[ ] Function used in multiple source files but not declared in header file.
[ ] Internal-use-only function not declared static.
[ ] Full struct definition in header files when components should be hidden.
[ ] #include "file.c"
[ ] Substantial repetition of code.

Miscellaneous

[ ] Other obstacle to readability not mentioned above.


CategoryProgrammingNotes


2014-06-17 11:57