On Jul 27, 2013, at 4:19 PM, Vincent Massol <[email protected]> wrote:
Hi,
On Jul 27, 2013, at 3:48 PM, Sergiu Dumitriu <[email protected]> wrote:
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!
In practice it is (as can be demonstrated by the state of the oldcore when we started working on it back in 2005) :)
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.
Yes logger is a good example of a field for which it's hard to write an intelligent comment ;)
+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){…}
Yes, for the repetitiveness, I've been using @see elements in all my code so that only the getter is documented.
These are bad comments obviously… FTR I had put a small javadoc guide with some example at: http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HJavadocBestPrac...
A good comment IMO is one that doesn't only explain what it represents but why it's there and that shows an example when the data is untyped. For example:
/** * The last person who made a modification to any part of this document (content, objects, etc). Note that this is different from the creator who is the person who first created the document. Example of author: "XWiki.Admin".
A better note would be: "Note that this is different from the content author who is the last person who made modifications to only the content of the document (changes to the document's objects or class doesn't change it)." Thanks -Vincent
*/ private String author;
Suddenly it becomes interesting: - we know it's about the last person who made a modification to any part of the document which was not clear from the field (and it'll explain the difference with contentAuthor too). - we have an example showing what an author string looks like (of course using a DocumentReference is even better since it's typed and clearly represents what is an author)
With DocumentReference:
/** * The last person who made a modification to any part of this document (content, objects, etc). Note that it points to a reference to that author's document representing it since we currently don't have a User object to represent a User. */ private DocumentReference author;
Future:
/** * The last person who made a modification to any part of this document (content, objects, etc). */ private User lastAuthor;
For this last example the comment becomes slightly less useful than in the previous examples but it's still useful IMO.
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.
I'm -0 but I'll follow the majority. It's not because it's hard to write good comments that we shouldn't do it… Obviously there are cases when it's really hard to find a good comment (like the logger for example) but you can be sure that not mandating comments will not make them automagically appear even for harder to understand cases. We can only hope that all the xwiki devs have by now been trained enough to write javadoc comments with our past strategy that they'll continue to write them wherever needed but even that will decay over time...
We'll see what happens :)
Thanks -Vincent