Comments
Write the least possible comments
Prefer coding to commenting
The code should document itself as most as possible
Many and long comments are code smell
Comments Should Be
Meaningful
Necessary
Readable
Bad Comments
„Commented out” code - Remove it, find it in the version control system
Separators, markers
Redundant
Misleading
Out-of-date
Obvious
Unnecessary
Funny
Closing brace comment
Attributes - author, date, issue number, etc.
Non-English
Too many HTML markers
Historical
Prone to copy-paste error
Good Comments
TODO comments
Warnings - e.g. "Not threadsafe"
Limitations - e.g. "It works only with a sorted list"
Javadoc comment to public API - for high level service methods
Comment empty blocks
Less is more.
Example: Bad: Comments
// Redundant, obvious:
/**
* gets the value of Name
*/
public String getName();
// Funny, unnecessary:
// I invented this part, but do not know why
Example: Good: Javadoc comment
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*
* @deprecated Use {@link getImage(Long id)} instead.
*/
@Deprecated
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
Last updated
Was this helpful?