Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
Omit parentheses for the general form of methods and constructors
When referring to a method or constructor that has multiple forms, and you mean to refer to a specific form, use parentheses and argument types. For example, ArrayList has two add methods: add(Object) and add(int, Object):
The add(int, Object) method adds an item at a specified position in this arraylist.
However, if referring to both forms of the method, omit the parentheses altogether. It is misleading to include empty parentheses, because that would imply a particular form of the method. The intent here is to distinguish the general method from any of its particular forms. Include the word "method" to distinguish it as a method and not a field.
The add method enables you to insert items. (preferred)
The add() method enables you to insert items. (avoid when you mean "all forms" of the add method)
OK to use phrases instead of complete sentences, in the interests of brevity.
This holds especially in the initial summary and in @param tag descriptions.
Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than 2nd person imperative.
Gets the label. (preferred)
Get the label. (avoid)
Guidelines
This chapter doesn't appear to contain any implementable rule. Proposal:
| Documentation Comments Rule |
Checkstyle Checks Used |
Sample files |
| Omit parentheses for the general form of methods and constructors |
-- |
|
| OK to use phrases instead of complete sentences |
-- |
|
| Use 3rd person descriptive |
-- |
|
Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
Omit parentheses for the general form of methods and constructors
When referring to a method or constructor that has multiple forms, and you mean to refer to a specific form, use parentheses and argument types. For example, ArrayList has two add methods: add(Object) and add(int, Object):
The add(int, Object) method adds an item at a specified position in this arraylist.
However, if referring to both forms of the method, omit the parentheses altogether. It is misleading to include empty parentheses, because that would imply a particular form of the method. The intent here is to distinguish the general method from any of its particular forms. Include the word "method" to distinguish it as a method and not a field.
The add method enables you to insert items. (preferred)
The add() method enables you to insert items. (avoid when you mean "all forms" of the add method)
OK to use phrases instead of complete sentences, in the interests of brevity.
This holds especially in the initial summary and in @param tag descriptions.
Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than 2nd person imperative.
Gets the label. (preferred)
Get the label. (avoid)
Guidelines
This chapter doesn't appear to contain any implementable rule. Proposal: