Comments in a Program#

Comments are critical components of a program, as they tell readers what your intentions are in the code, in English. All of your files should have three kinds of comments: a file header, method headers, and in-code documentation.

File Header#

A file header starts each file, in which you provide your name, and the date, and describe the purpose of the file in your own words. Often students will say “This is for Assignment 1”, but such comments are almost useless because the reader may not know what Assignment 1 is. You should describe your task or tasks in your own words because that will complete the file. Furthermore, being able to write about your task will make it easier for you to program the task. It is good practice to write (at least part of) the file header first so that you are more focussed on the code you need to create.

Method Headers#

Methods headers should be present above each method and be enclosed in the standard Java docString format, that is, begin with /**, contain *s along the left side of each line, and end with */. Inside the method header, you should have a precise summary of the method and describe each parameter (use @param) and the return value (use @return). Note that most Integrative Development Environments (IDEs) will create the form of a method header for you.

In-Code Documentation#

In-code documentation, including inline comments, should be present when they help clarify your code. Sometimes people think that there must be a comment on every line of code, but this is not the case. Too many comments can make your code less readable; incorrect comments can make your code completely unreadable. If you are still someone who likes to translate your code into English with a comment, then it is time to start to eliminate those comments from your code. Assume that people, including you, can read code (that is, they know what the statement does). Add comments to help with questions such as why that works or how that achieves the goal or when the statement is applicable. Consider the following example:

p = x + y; //Add x to y and put in p

This comment is not useful because it is a direct translation of the Java code to English.



Now consider the new comment in this code:

p = x + y; //Add February’s total to January’s total to build towards the total of all months

Now this comment is adding critical information: it tells why this works because it explains the variables and it tells how we are moving towards the goal of having the complete total of all months.



BUT, now consider the following:

monthsTotal = FebruaryTotal + JanuaryTotal;

There is no comment, and yet the code is more readable than either of the previous two statements. Why is this? Good variable names go a long way in making code clear.

Recap of for Whom to Write#

The best rule when deciding on documentation is to remember that you are writing for people, so determine whether that potential comment will be helpful to people (so leave it in) or will it add drudgery (so leave it out), or whether you can write the code in a way that makes the comment redundant (so leave it out)? When you are keeping important information in your head, e.g. assumptions, then you must indicate those in your code as comments since other readers cannot guess your assumptions.

Later, when we do object-oriented programming, you will also be adding documentation for classes, i.e. class headers.