First, I disagree with Reek's point number 4. The problem with <tab> characters, in addition to indenting code too much, is that their meaning (how wide a tab stop is) is always interpreted by software. Your editor, my editor, a printer, and commands such as cat, less, and tail might all substitute different numbers of spaces for each <tab> character in your source code, making it very difficult to read. The only solution is to type spaces explicitly to indent your code, or better yet, to use a "real editor" to substitute spaces whenever you press the Tab key to indent your code. On UNIX, pico is easy to use, but is not useful for editing source code because, among other things, it does not allow you to substitute spaces for <tab> characters. On Windows, Notepad has the same problems. However, vim is a good programming editor for UNIX, and pfe, [ available here ], is a good programming editor for Windows.
Also, I find that an indent of 2 spaces is perfectly legible, whereas the problem of code getting squeezed at the right side of the page when using an indent of 8 is very constrictive, contrary to what Reek says. For this course, you can use any size indent you want, but in no case is any line of code, whether it is part of a statement or a comment, to extend past column 72.
/* printargs.c * * This is the main module for the printargs application. * * main Prints command line arguments and environment * variables. * * C. Vickery * Spring 1999 */Put
#includedirectives after the file header comment block.
/* Global Variables */
Use some sort of horizontal line, such as a row of dashes or asterisks to make it easy to find the beginning of a function header. Don't put horizontal lines elsewhere in the file.
/* main() * -------------------------------------------------- * * Parameters * * arc Number of command line arguments. * argv Array of command line argument strings. * envp Array of environment variable strings. * * Return Value * * 0 Normal program exit * 1 Error exit * * Calls do_print to print the command line arguments, * then prints the environment variables and exits. * */
If a function implements a complex algorithm, use a comment line to introduce the steps in the algorithm. These comments should parallel the algorithm outline given in the function header.
For example (assuming the function header given above):
/* Call do_print to print the command line arguments. */ <code to call do_print goes here> /* Print the environment variables and exit. */ <Code to print the environment variables and exit goes here.>
/*************************** * * * Life is too short to * * spend time drawing * * boxes around comments! * * * ***************************/
There are two reasons for this rule: