Parent issue: #19807

Coverage table

Chapter link

Content

Image

Text

Use "this" instead of "the" when referring to an object created from the current class.

For example, the description of the getToolkit method should read as follows:

Gets the toolkit for this component. (preferred)

Gets the toolkit for the component. (avoid)

Add description beyond the API name.

The best API names are "self-documenting", meaning they tell you basically what the API does. If the doc comment merely repeats the API name in sentence form, it is not providing more information. For example, if method description uses only the words that appear in the method name, then it is adding nothing at all to what you could infer. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the API name.

Avoid - The description below says nothing beyond what you know from reading the method name. The words "set", "tool", "tip", and "text" are simply repeated in a sentence.

/**
* Sets the tool tip text.
*
* @param text  the text of the tool tip
*/
public void setToolTipText(String text) {

Preferred - This description more completely defines what a tool tip is, in the larger context of registering and being displayed in response to the cursor.

/**
* Registers the text to display in a tool tip.   The text 
* displays when the cursor lingers over the component.
*
* @param text  the string to display.  If the text is null, 
*              the tool tip is turned off for this component.
*/
public void setToolTipText(String text) {

Be clear when using the term "field".

Be aware that the word "field" has two meanings:

• static field, which is another term for "class variable"
• text field, as in the TextField class. Note that this kind of field might be restricted to holding dates, numbers or any text. Alternate names might be "date field" or "number field", as appropriate.

Guidelines

This chapter doesn't appear to contain any implementable rule. Proposal: