Comments, Quality Matters

Goal: To make your code as readable as possible. Focus on Quality, rather than Quantity for source code, in line comments. Provide long description and stories in external supporting documentation.

1. Every class must be Javadocs documented explaining its purpose and what it does. Use the following style:

/**
* This immutable class represents <i>complex
* numbers</i>. 
*
* @author David Flanagan
*/

Do not provide version, date created, date updated etc. These comments are for explaining what the class does and are not for source control. Look at the ugly example below:

// bad style - dont do this
/**
* This immutable class represents <i>complex
* numbers</i>. 
*
* @author David Flanagan
* @date September 25, 1999
* 
* Version 1.1
* Last Modified: March 3, 2003
* Revisions
*     Umer  (25/09/2001) - Added code to calculate the complex plane
*     Jerry (29/01/2002) - Modified Umer's code
*  
*/

The above code is taxing and is unrealistic to maintain. If we need this information, we obtain it from Git. [git log, git diff and blame are your friends]

2. Every method should have a Javadoc explaining its purpose. Try to be concise and to the point.

Below are examples of a few methods, where the comments are NOT necessary.

/**
 This method returns the name of employee
*/
public String getEmployeeName() { return employeeName; }

/**
 This method sets the name of employee
*/
public String setEmployeeName(String n) { this.employeeName = n; }

3. Be concise, not silly

Comments are not subtitles. You are writing comments mainly to help you understand your code later and other programmers to read your code. However, refrain from doing the following:

// -- lame commenting example 
// Loop through all IPs in the IPList
foreach(ip in ipList) 
{
    socket.sendUrgentData(ip);  //send some urgent data to each ip address
}

If you remove every single comment from above, it is still readable.

4. What the FUCK is this?

I have seen code (Java but mostly PHP) where a script begins with something like this:

######################################################
# Name: website_stats.php                            #
# Objective: To collect all the stats from log files #
#            and display them in a grid to the users #
# Author: The-Guy-With-Too-Much-Time-On-His-Hands    #
# Date: September 25, 1999                           #
######################################################

This looks good. However, comments like this cannot be maintained. Try changing the text above without ruining the symmetry of the box.

Note: I have been guilty of doing this in my PHP scripts. It was always messy trying to add more information and wasting 5 minutes just aligning the box to maintain its symmetry.

Best Explained With Examples

Let us consider the following examples:

Example #1:

// -- bad - too wordy and giving out useless information => violates the Quality criterion of our Principle
/** 
 This is a String variable which stores an employees name. The name
 must begin with an Uppercase and should not be longer than 255 
 characters. The name is declared a private variable so we have
 provided accessors and mutator methods. Because the name is final,
 it must be set in the constructor.
 **/
 private final String abc;

Example #2:

// -- OK - but could be better
private final String abc; //For storing a employees name

Example #3:

// -- Best - The variable itself conveys its purpose
private final String employeeName;