Bernd Fondermann wrote:
Emmanuel Lecharny wrote:
Bernd Fondermann wrote:
To turn this into an actually task, could you point out areas/classes
that especially lack javadoc?
I have conducted a quick review of around one third of the java files
(test excluded). I have tagged all the files I reviewed with :
* J : files without javadoc
* j : files with partial Javadoc
* H : files without a description in the header
* A : missing @author tag
* OK : files with all the needed javadoc, header and @author tag
Some of them combine mor ethan one of those missing elements.
I have found only 8 OK files oit of 96 files I checked. Here is the list
(files without one of those tags haven't be checked yet)
Note that I may have been inaccurate to some extent.
Probably not, thanks for putting this together.
I have to admit that this kind of quantitive analysis doesn't tell me
much. I'd rather improve the javadoc for a central class than write a
new one for a simple interface setter method where the name and
parameters speak for themselves.
Quantity... Sounds like an enemy of Quality :) Being an old fart, and a
bit rigid too, as a rule of thumb (not talking about Vysper here), all
the crappy programs I had to deal with *always* had crappy - or missing
doco. On the other side, doco all over the code never indicate any level
of Quality.
Here, I would like to get out of this Quantity vs Quality debate,
because it's a dead end. My POV is that documented program is always
easier to understand by new comers. Another aspect is that whatever you
do, you won't be the maintainer of the code you write forever, so better
think about the next guy, something like 'write code for the average
programmer'.
I don't like over documented code, for instance (I mean, comments
*inside* the code). Just because if you needed to add some comments in
your code, that means your code is probably too complex to be understood
by a normal human being (ie , the 'average programmer' ;), and you may
have to split the code a bit. The very same applies for naming. Not
being english native speakers make it difficult to use the exact correct
name for a field or a function.
Now, that does not apply for Javadoc, as it's intended to be exported to
produce some cool HTML pages someone may look at occasionally (when you
send the guy a RTFM for instance ;)
(I started programming when CPUs where slow, RAM was sparse and the
significant characters of a variable that were recognized by the
compiler were limited to the first 12 or so.
Today, we have code completion and no shortage of method or variable
name lengths. I try to make heavy use of that.)
Talk to me about that !!! When I started writing code, it's was either
basic or assembly langage (Z80, 8080 or 6502). My first computer was
having 16 Kbytes (yeah, kilo !). I even had to *count* cpu cycles for
each operation to know how long the program will take... It was back in
1982 (I'm not talking about my old TI57 with 49 program steps (ie, 49
*bytes* of memory ...)
Sometime you just have to remember where you came from to see how
pleasant this present time is !
It's like your total unit test coverage number. It doesn't tell you
anything about your test quality.
Absolutely.
But if you point out critical code that misses a javadoc, unit test or
spec compliance annotation or code comment, you'll never find me
disagreeing with you. (I reserve the right to ask for a patch, though. ;-)
As a general politic, I think that the one who write the code at first
is the one who *knows*. Hopefully, modern IDE generates all this boring
Javadoc for setters and getters. Otherwise, I don't think that adding
headers for private method is always mandatory (sometime it helps). It's
all about how easy it is to understand what a method do. However, what
seems easy for you might be a bit more complicated for someone just
diving into your code.
I personally find it polite to add headers and javadoc, it makes the
code more welcoming. Like names for the street and number on the doors.
So my question is, where is that code which most deserves being improved
in this way?
Well, without having done the quality analysis yet, my answer, not a
surprise, will be : all the interface and public methods without Javadoc
;) Very PC, I know ...
But as this is not the answer you are expecting, so give me a couple of
week, if I can find the time to dive into the code.
Thanks !
--
--
cordialement, regards,
Emmanuel Lécharny
www.iktek.com
directory.apache.org
