Checklist for good programming

This checklist should help you write high-quality programs.
Raphael Finkel, 8/17/2005

• Identifiers: Make sure all your identifiers are meaningful.
  1. One-letter identifiers are almost never meaningful.
  2. Names like flag and temp are seldom meaningful. Instead of flag, consider naming the Boolean condition it checks for, such as valueFound.
  3. Consider multi-word identifiers, like nameIndex. Long identifiers (within reason) tend to be very readable.
• Bare literals: Avoid numbers other than 0 and 1 and strings other than "" in your program except when you define constants.
  1. Don't use a literal integer as an array bound.
  2. Don't use a literal integer as a run parameter, such as a timeout or port number.
  3. Don't use literal integers to select menu entries.
  4. Don't use a literal integer to measure the size of a string or some data; use sizeof() and strlen() in C and C++ and .length() and .size in Java.
  5. Don't use a literal string for a file name. You may output literal strings, though.
  6. Don't use a literal integer to index into an array containing heterogeneous data.
  7. Don't declare an identifier with a name denoting a literal, such as "thirty".
• Modularization: A program is built out of interacting components.
  1. Don't put all your code into the main() routine.
  2. In fact, don't make any routine do too much work. If it's longer than about 50 lines, it is maybe too long.
  3. If you duplicate code several times, consider whether a loop would work better, or perhaps a subroutine.
  4. If you find you are indenting very deeply, you most likely aren't using subroutines when you should.
  5. Don't reinvent library routines (unless your assignment requires it). Look in the manuals to learn about sprintf() and atoi(), for instance.
  6. Use header files in C and C++ (header files have names ending .h) to define all constants needed by multiple files and declare all subroutines exported between files. But don't put the body of subroutines in header files (with the rare exception of inline subroutines).
• Formatting: Your program should be easy to read.
  1. Look at http://geosoft.no/development/javastyle.html for clear suggestions on formatting and other presentation issues. This reference is specifically directed at Java, but it has value for other languages, too.
  2. Try to restrict all your lines to 80 characters; many people view code in 80-column windows for historical reasons.
  3. Don't use both tabs and spaces for indentation, because not all text editors treat tabs as exactly 8 spaces.
  4. Do follow a consistent indentation pattern that reflects the program's control structure.
  5. Don't put lots of blank lines in your program. One blank line between subroutines is enough.
  6. Different operating systems terminate lines different ways. If you move between Win32 (which uses \r\n), Unix (which uses \n), and MacOS (which uses \r), reformat your file to use a consistent termination method.
  7. Don't set the executable bit (Unix) on your source files.
• Coding: You want your coding to be clear, maintainable, and efficient, in that order. Some of the rules here are very specific; others are more general.
  1. Don't use a sequence of if statements that have no else if only one can match; use else if.
  2. When you want to categorize text input, don't enumerate the possible first characters.
  3. Use shift operators instead of multiplication for constructing bit patterns.
  4. In a switch statement, always check for the default case. Likewise, in a sequence of if-then-else statements, use a final else.
  5. All system calls can fail. Always check the return code, and use perror() to report the failure.
  6. Booleans should always use the boolean type in Java, bool in C++, and 0/1 integers in C. Don't use characters t and f, and don't use -1 and 1.
  7. Use loops to initialize data structures if possible.
  8. Use each variable and each field of a structure for exactly one purpose. Don't overload them unless there is an excellent reason to do so.
  9. Don't use the same identifier for both a type, a variable, and a file name, even if you change the capitalization. It's too confusing.
  10. If you are modifying data with htonl() or a similar routine before network transmission, don't modify the data in place. Build a second data structure.
  11. Try not to use global or nonlocal variables. Declare each variable in the smallest scope you can. There are legitimate uses of nonlocal variables, but make sure you really need them.
  12. Shell and Perl programs should have their #! line as the first line of the file; otherwise, the line is just a comment.
  13. Try to avoid coding special cases. You can often use pseudo-data or other data-structure methods that allow you to fold special cases into the regular cases.
• Compilers: Let them help you find mistakes
  1. Always invoke compilers with all warnings enabled. For C and C++, use the -Wall flag; for Java, use -Xlint:all -deprecation.
  2. All Perl programs should run with the -w flag and should have use strict. All Perl cgi-bin scripts should have the -T flag, too.
• The make utility: Use it, and use it well.
  1. A makefile should always have a "clean" recipe, which should remove all files that can be reconstructed by other recipes in the makefile, including object and executable files.
  2. If your project has multiple source files, the makefile should generate object (.o) files as needed and link them together.
  3. The makefile should be written so that if you run make twice in a row, the second run does no recompilation.
  4. Every recipe should create the file specified in its target.
  5. Every recipe should use every file specified in its prerequisite list.
  6. Learn to use rules for targets like .c.o to avoid repetitious makefiles.
  7. If you have just one C or C++ source file, the executable file should have the same name (without the extension .c or .cpp).
  8. Make sure you list all .h files as prerequisites where they are needed. Consider using makedepend to generate the prerequisite list for you.
• Documentation: It's not just just for the grader. It helps you as you write the program, too!
  1. Add documentation as you write the program. You can always modify it as your design changes.
  2. Include external documentation: How does one compile and run the program, and what is it meant to do? The external documentation could be in a separate file; for small projects, it can be a comment in the single source file.
  3. Include internal documentation: What algorithms and data structures are you using? An overview can be in a separate file, but usually internal documentation is placed on the specific routines, declarations, and steps that it describes.
  4. Check your whole program and documentation for spelling mistakes. It is impolite to turn in misspelled work.
  5. Check all your documentation (and output messages) for grammar mistakes.
  6. Programs are much more readable if you put a short comment on closing braces. For instance, the brace closing a conditional can have a comment like "if value looks good". A brace closing a loop can have a comment like "for each input line". A brace closing a procedure can have a comment just naming the procedure. A brace closing a class can have a comment saying "class" and then the name of the class.