27 Jul
2013
27 Jul
'13
3:48 p.m.
On 07/26/2013 04:47 PM, Caleb James DeLisle wrote:
Hi,
To promote contribution and encourage code brevity, I would like to remove
the rule that we fail the build over a missing javadoc on a non-public
field.
It's important to understand, this is *not* about encouraging developers
to skimp on documentation!
There are obvious cases such as 'logger' where the role of the field is
blatantly clear and forced documentation is at best useless and at worst
counterproductive because it creates an information overload for the code
reader and hides the comments which the author really wanted to be seen.
+1 for dropping this rule
+1. The best rule about commenting code is that comments should only say
what the code can't. Sometimes it's hard to come up with a good
non-repetitive comment like:
/** The author of the document. */
private DocumentReference author;
/**
* Get the author of the document.
* @return the author of the document
*/
public DocumentReference getAuthor(){...}
/**
* Set the author of the document.
* @param author the new author of the document to set
*/
public void setAuthor(DocumentReference author){...}
Since most of our code is now components, we must continue to thoroughly
document all our APIs (roles), but internal implementation details are
better documented by inline comments that actually explain tricky points
in the code, instead of reexplaining parameter names that should already
have Understandable Names.
--
Sergiu Dumitriu
http://purl.org/net/sergiu