Good Commenting Technique


General

  • Does the source listing contain most of the information about the program?
  • Can someone pick up the code and immediately start understanding it?
  • Do comments explain the code's intent or summarize it, rather than just repeating it?
  • Is the PDL-to-code process used to reduce commenting time?
  • Has tricky code been rewritten rather than commented?
  • Are comments up to date?
  • Are comments clear and correct?
  • Does the comment style allow comments to be easily modified?

Statements and Paragraphs

  • Does the code avoid endline comments?
  • Do comments focus on why rather than how?
  • Do comments prepare the reader's mind for what is to follow?
  • Does every comment count? Have redundant, extraneous, or self-indulgent comments been removed or improved?
  • Are surprises documented?
  • Have abbreviations been replaced?
  • Is the distinction between major and minor comments clear?
  • Is code that works around an error or undocumented feature commented?

Data Declarations

  • Are units on data declarations commented?
  • Is the range of values on numeric data commented?
  • Are coded meanings commented?
  • Are limitations on input data commented?
  • Are flags documented to the bit level?
  • Has each global variable been commented where it is declared?
  • Has each global variable been documented each time it's used, either with a naming convention or a comment?
  • Is each control statement commented?
  • Are the ends of long or complex control structures commented?
  • Are magic numbers documented or, preferably, replaced with named constants or variables?

Routines

  • Is the purpose of each routine commented?
  • Are other facts of each routine given in comments, when relevant, including input and output data, interface assumptions, limitations, error corrections, global effects, and sources of algorithms?

Files, Modules, and Programs

  • Does the program have a 4 to 5 page document such as that described in The Book Paradigm that gives an overall view of how the program is organized?
  • Is the purpose of each file described?
  • Is the author's name and phone number in the listing?