forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Importance of Javadocs
Date Fri, 08 Jul 2005 07:57:24 GMT
With Anil working on the eclipse plugin we find that we are now having 
to manage Java code as well as XML/XSLT/configs. With all our files we 
are very keen to have extensive comments in them to aid maintenance by 
other devs. I'm writing this mail to state *my* opinion on Javadocs in 
Java files for the same purpose. I want to ensure that my opinion 
reflects that of the community before I go enforcing anything on Anil 
(and anyone else providing patches for the Eclipse plugin).

I believe that, whilst a long way from perfect, Javadocs are critical to 
the development and management of good Java code. Whilst the purpose of 
a given class or method within a class may seem obvious to the initial 
author at the time of writing it is rarely obvious to others or even the 
original author after a period of time.

Furthermore, the easies way to find what you want in Java code is via 
the documentation generated from Javadoc comments. This is true for most 
common Java editing environments which provide context sensitive help 
for Java code based on the javadoc comments.

It is my intention insist on patches having adequate Javadoc comments 
before I apply them. Is the community in general agreement here or am I 
being too draconian?

(I'll be taking silence as consensus with, or indifference to, my view)

Ross


Mime
View raw message