Do not do pointless commenting. All of the below comments added no extra meaning to the source code and should have been left out.
public class AuthorKeywords
{
/** The keywords. */
private String[] keywords;
private int startYear = 1989; // assign 1989 to startYear
private dataPath = null; // clear the value of dataPath
:
/**
* getter for the startYear value
*/
public int getStartYear()
{
return startYear;
}
:
A more useful set of comments for the same source code are listed below.
Even if comments on simple code is missed, complex code should always have a comment at the beginning describing what the philosophy of the code is, what it is trying to accomplish. Source code that is doing a complex activity should be heavily commented. Source code that has an underlaying philosphy it follows should be commented.
/**
* This class represents a logical index by keyword of all books
* written by an author we have in our database.
*
* Note that it is just a container for storing and reading
* the book data but the contents are wrapped by useful
* methods to make them easy to access.
*
* Author: MB
*/
public class AuthorKeywords
{
/**
* These keywords are used to find the record when the
* user searches for books by word associations
*/
private String[] keywords;
private int startYear = 1989; // earliest possible data date
private dataPath = null; // where this data came from
/**
* @return the earliest year that we found information
*/
public int getStartYear()
{
return startYear;
}
:
This is further illustrated by another example. The following model class, Media.java had a small amount of Javadoc at the top of the file. Clearly, if a file was called Media.java and the classname was called Media, the file is designed to hold media information. But still the developer added a comment presumably to remove a Javadoc warning – a waste of effort.
/**
* Represents the Media
*/
public class Media implements BaseModel
{
:
/** The storage folder. */
private String storageFolder;
/** The queue. */
private Queue<Thumbnail> queue;
Perhaps the Media class was so simple it did not require comments. But where is the Media class intended to be used? What are the restrictions on using it? How are the private variables intended to be used?
The solution should have been to either remove the Javadoc build warning or to write more meaningful comments. The latter is easier and makes the developer a stand-out player on the team.
/**
* This is the Media model class, which represents the 'media'
* table in the database, and contains most 1:1 attributes of a
* media clip.
*
* It is the core entity in this application and describes a
* physical binary video file.
*
* Refer to Media.hbm.xml for the column-to-property mappings.
*/
public class Media implements BaseModel
{
:
/**
* The root folder where all encoded videos for this
* media get stored.
*/
private String storageFolder;
/**
* Queue of thumbnails yet to be generated for this media.
*/
private Queue<Thumbnail> queue;
}
In most cases a class has a reason to exist and it only takes a minute or two to write this down in a comment.
Tip: Comment the philosophy of what you are trying to do AND any comment code that might be confusing to those who come along after you. You may be run over by a bus tomorrow, and you wouldn't want to inconvenience anyone, would you?
