Menu
Given the following code snippet:
/**
* Initializes a new instance.
*
*/
public Collector() {
this.map = new HashMap<>();
}
Please concentrate on the Javadoc comment: There does not happen very much in this constructor. So, whats the proper way to write Javadoc for it? As is shown above? That would be perfectly accurate but superfluous at the same time, because a constructor is meant to initialize a new instance.
So, on one hand, we do not want to write redundant information in Javadoc comments, on the other hand, there has to be a Javadoc comment (has it?).
So, in short, how to write meaningfull, not redundant Javadoc in such situations?
398
Doc comments for constructorsIt's a best practice to include a constructor in a class. However, if the constructor is omitted, Javadoc automatically creates a constructor in the Javadoc but omits any description of the constructor. Constructors have @param tags but not @return tags.
In general, Javadoc comments are any multi-line comments (" /** ... */ ") that are placed before class, field, or method declarations. They must begin with a slash and two stars, and they can include special tags to describe characteristics like method parameters or return values.
Nope, you shouldn't write javadoc for private methods. End users don't have access to private fields or methods so there really isn't a point in providing javadoc for them. Private fields and methods are only meant for the developer. If you really need to though, feel free to write comments for non-obvious logic.
Javadoc scans your source files looking for documentation comments, also known as “Javadoc comments”. They begin with /** (two stars) and end with */ (one star).
It depends on who is the reader of the code and how obvious the constructor's functionality is. Either the javadoc is the only source of information for a reader (closed-source), or the reader can easily grasp what's going on in detail from the source. In our projects, we do not javadoc obvious functionality at all. When some formalism requires javadoc, we simply use /** Constructor. */ to just satisfy the formalism.
112
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
