Coding: Comments

Comments help anyone who has to read the code. This is most often another programmer. It could also be the original programmer, some time later, at which point he has forgotten exactly what some algorithm does, or the use of some variable. Therefore, it is imperative that comments be accurate! Even a total lack of comments is far preferable to comments that are untrue.

To ensure that there are sufficient comments, and that they are accurate:

• Each file, and each function, dialog, or other large section within a file, should have a header, that includes at least the name of the file or section, and its purpose. (For files, the "purpose" should include the program or library to which it belongs.) Do NOT rely on SourceSafe, RCS, or other such tools, to keep track of version history -- the company may change tools, plus extracting the information for a given file can be very cumbersome, and sometimes unreliable.

  Each function should also include in the above header:

  • All parameters, including the name, purpose, and whether the data is only read, only written, or both read and written
  • The significance of any return value
  • The name, purpose, and access type of each file it reads and/or writes
  • All other side effects, especially on parameters, but also including on global variables
  • Its complete revision history, including its original creation, with the date, initials, description, and reason for EVERY CHANGE. This includes incorporation or extraction of other functions. (Mere cosmetic changes may be omitted, or summarized as "cosmetics".)

  Desirable, but not strictly necessary, is a list of all major functions calling it, and of all major functions it calls (written by the company, not in the language's standard library).

  Each file should also include in the above header:

  • at the very top, a copyright notice (for the purpose of protecting the company's "intellectual property"), including the year (creation, latest revision, and all changes between) and company name, in proper legal format (e.g., "Copyright 1998, VBC Inc.").
  • what unusual compilation/linking/etc. parameters are needed; if none, state so.

• Each variable should have an explanatory comment -- see Variables.

• Each line of code that is not immediately obvious (to someone who knows the language but has never seen this project before) should have a comment. If the comment is short enough that it can fit on the same line, it may go there, else it should go immediately above the code.

• Each ending delimiter (closing brace, "END", etc.), more than one screenful below the matching opener, should have a comment on why the lines of code enclosed are grouped. For examples:

      { end if eof (infile) }
      END;
  
      /* end void dsFooBar() */
      }
  
      // end class FOOBAR
      }
  
      ! end while we have widgets left to process
      endwhile;

  See also Block Delimiters for notes on alignment.

• If a large chunk of code has commented out, make it clear at a glance that the code is dead, rather than simply using multi-line comment delimiters or compiler directives at the beginning and end of the chunk. For instance, use "to eol" comment delimiters in front of EACH line, or "box" it, like:

   /******************
    * a = b + c;     *
    * d = e - f * g; *
    ******************/

  or at least

   /*
    * a = b + c;
    * d = e - f * g;
    */

  In cases where the code to be commented out already includes comments, a conflict can arise between the delimiters of the original comments, and the "commenting it out" delimiters, so be careful! "To eol" comment delimiters (e.g. C++'s "//" and Ada's "--") are much safer in this context.

• When a section of code is "cloned" for some other purpose, and then changed (be it a new function in the same project, or for another project), any relevant comments must be changed at the same time as the code. (You may delete prior historical comments and reference the original, if it can be guaranteed to still exist as long as the clone code.) Names of functions, variables, classes, etc. that were strictly relevant to the prior purpose must also be changed. (If a function is relevant to both purposes, it probably should be extracted to a common function, or library if for multiple programs.)

• Likewise, when code is changed for any other reason, all comments should be inspected and changed if necessary.

• To detect accidental truncation, which can easily be caused by crosslinked clusters, buggy version control software, etc., each file should also have a comment declaring the end of the file. Nothing should ever be after this!