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