Coding Style

If an item is marked as Required do not waste your time trying to convince me otherwise. Items marked WTD are worth a shot if you have strong feelings on the issue.

1. Required Formatted to fit in 80 columns. If your code is wider, insert line breaks so that it is readable in 80 columns.

2. Required Indented by two spaces per block. Less indentation makes reading difficult, more is just a waste of space.

3. Required Cleaned of extraneous line breaks. If readability requires whitespace, one blank line is visible, two is just wasted space.

4. Required Named properly. Header files are named with the .h extension, code files are named with the .C extension. No exceptions.

5. Required Protected headers. Header files should have all code enclosed in #ifdef protection blocks to prevent multiple includes. My preferred name scheme is __HEADERNAME_INCLUDED, so a typical header for a file defining buffer utilities would look like:

   /*
    * CVS Comment block
    */
   #ifndef __BUFFER_UTILS_HEADER_INCLUDED
   #define __BUFFER_UTILS_HEADER_INCLUDED
   
   Code....
   
   #endif
   

6. Required Complete headers. Header files should #include all of the other headers needed for the types used by the header and no others. An easy way to check conformance is to #include a header as the first line of the corresponding code file, e.g. if I am developing code for buffer utils in bufutils.h and bufutils.C, the first line after the CVS comment block in bufutils.C is:
   #include <bufutils.h>

7. Required Braces and linebreaks. In general, a opening curly brace should never appear on a line by itself, while a close curly brace usually should (but see Method definitions for an exception). This allows blocks to be quickly associated with their selectors and easily skipped. Examples:

     if(x > 5){                 if(x > 5){
       y=2;                       y = 2;
       z=5;                       z = 5;
     }                          }else{
     x = y+2;                     y = 4;
                                  z = 10;
                                }
                                x = y+2;
   
     while(x > 5){             
       x--;
       y++;
     }
   

   Note: If you do not need braces, do not use them, since it is a waste of space. Always write:

   if(x > 5)             NOT: if(x > 5){
     y = 10;                    y=10;
                              }
   

8. WTD Method definitions. There is some flexibility here - my own preferred form is:

   void
   MyClass::MyMethod(int x, int y):
     Initializer(x),
     Initializer(y)
   {
     Body of the code
   }
   

9. WTD Separated into files. I hate projects which do not split source code into multiple files. The general rule is usually one class means one header file and one source code file. There are exceptions to this rule, particularly for short classes which are tightly coupled (such as a base class and derived classes). If there are multiple classes in a pair of header and code files, the code file must maintain the same ordering as the header file.

Pet Peeves

Code with hardcoded paths. Insane, tiring, etc.... Every language has facilities for dealing with paths and names. Use them. A program which only works on "Data.in" is next to useless. A program which only works on /home/student1/myfile.in is worse.
This applies to HTML pages and scripts as well as code. Unless a link is going off-site, it should be relative to the current page.

Verbose code. To increment a variable in C/C++, use x++; but never use x = x + 1;. In general your code should be as concise as possible, even sacrificing readability for those who are not expert C programmers.

Inefficient code. The following bit of insanity is all to frequent:

if(!strcmp(param, "-b"))
  p = 1;
if(!strcmp(param, "-c"))
  p= 2;
and so on....

if(!strcmp(param, "-b"))
  p = 1;
else if(!strcmp(param, "-c"))
  p = 2;

if(param[0] == '-')
  switch(param[1]){
  case 'b':
    p =1;
    break;
  case 'c':
    p = 2;
    break;
 }