How to Comment Your Code
Anthony Hornof - May 2, 2020

Please comment your code. Please write standalone programmer's documentation, but also please comment your code. The two sets of writing—the comments in the code and the programmer's documentation—should complement each other. They should be consistent, but you should not simply copy from one to create the other. They are different, and serve two different purposes. For example, the comments in the code should explain the entire flow of control through all lines of code code, whereas the programmer's documentation should provide an overview of that flow of control, and the design philosophy that was used when writing the code.

An important aspect of engineering—applying math and science to build useful complex products and machines—is explaining how the products and machines actually work. The absence of comments in computer code, and the absence of programmer's documentation is, arguably, a failure to apply engineering principles to build something useful, and to some extent a breach of ethics. It is important that you comment your code.

Four kinds of comments that you should generate:

  1. Header information at the top of the file that describes what the file is. This should include the name of the file, the purpose or function of the file, the creation date, and the names of the initial authors. If the file is part of a larger system, the header comment should briefly describe that system, and how this file fits into that system. Lastly, the header might include a list of modifications made to the file, including when they were made, and who made them.
  2. A comment for every variable and constant that gets declared and assigned. The comment should explain what the variable or constant is used for and, if the initial value might be changed across runs, its default or typical settings. A similar comment could be provided for packages or libraries that get loaded, explaining the purpose of each, and why it is included.
  3. A blow-by-blow narrative of how the code works. This includes a comment for every block of code, such as every conditional statement, or lines of code that serves a specific function. The comment should appear above the block of code and serve as a sort of topic sentence for the block of code (sort of as if the lines of code were a paragraph of text). The comment provides a human-readable narrative of the machine-readable text.
  4. Formatting comments that organize the code and make it easier to read. These could be, for example, comments that create a horizontal line across the source code file, creating a break between sections of code, and making it easier to move the eyes directly to things like the start of functions.

Examples of well-commented code:

These examples are all PDF files so that you can see the comments in a different color of text. You should always do your programming in a text editor that colorizes the text. (And you can usually modify the colors if you need.) It is also useful to be able to see line numbers while coding, to help you keep track of where you are in the code file.

ANOVA_tracking error.r (PDF) by Anthony Hornof and UO graduate student Yunfeng Zhang
This code is written using the R statistics package. It runs an ANOVA (analysis of variance) on some joystick movement data.

EyeDrawButton.cpp (PDF) by UO undergraduates Anna Cavender and Rob Hoselton.
This C++ code was the base class for creating buttons that the user could "click on" by just looking at them, from the EyeDraw program.

fixfunc.c (PDF) (written by engineers at L.C. Technologies )
This C code was written for the eye tracker device manufactured by this company. This was the device used with EyeDraw. This code parsed raw eye tracking data (which arrived every 17 ms) to identify stable gaze fixations (roughly three or four per second). Just the first two pages of code are shown, with nicely-formatted comments for the variables.
(Downloaded from https://github.com/deslion/EyeTrackingProject/blob/master/ETRAN%20package/ETRAN_0.91/src/fixfunc.c on May 2, 2020).

Nilsen-dev.lisp (PDF) by Anthony Hornof
This Lisp code simulated a human-computer interaction experiment in which the user selected items from a pull-down menu. The code was used as part of a larger computer program that simulated a human moving the eyes and hands to do the task.

Some additional ideas on how and why to comment your code.