Obviously, the variables are as important as the methods, and the mere fact that they just occupy so little space in the source code should not relieve the designers from documenting them well. We also believe that the class comments are very important too. The class functionality should be clearly outlined up front, so no one would be forced to browse through the pages and pages of the source code to find out what is a functionality of the class in question. Therefore, we always write the class comments and place them inside the class definition - to stress that those comments really belong to the class being defined. Well written comments should convey information in a clear, precise and terse manner.
Excessive verbosity is almost as bad as lack of any comment at all.
You should always format your comments accordingly to the return type. We would place Java behind the Smalltalk and Eiffel, in this respect. If there is no adjective available that would suggest a true or false property, such as greedy , then use the prefix is , as in isOnLine . There are some words in English, such as get that tend to be overused in daily usage, and this habit trickles down to the programming as well. To illustrate this point, here is a flat list of get-ish methods extracted from java.awt.TextArea .