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 string for a file name. You may use literal strings, though, for output.
  3. 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 function.
  4. If you find you are indenting very deeply, you most likely aren't using functions when you should.
• * Formatting: Your program should be easy to read.
  1. Try to restrict all your lines to 80 characters; many people view code in 80-column windows for historical reasons.
  2. Don't use both tabs and spaces for indentation, because not all text editors treat tabs as exactly 8 spaces.
  3. Do follow a consistent indentation pattern that reflects the program's control structure.
• * 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. In a switch statement, always check for the default case. Likewise, in a sequence of if-then-else statements, use a final else.
  3. Booleans should always use the bool type in C++. Don't use characters t and f, and don't use 0 and 1.
  4. Use each variable for exactly one purpose. Don't overload (reuse) them unless there is an excellent reason to do so.
  5. 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.
  6. DO NOT use global or nonlocal variables. Declare each variable in the smallest scope you can.
• * Compilers: Let them help you find mistakes
  1. Always invoke compilers with all warnings enabled. For C and C++, use the -Wall flag. In other words, don't ignore warnings!
• * 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 and shows the quality of your early education.
  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 block in an if statement 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.