forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Cyriaque Dupoirieux <Cyriaque.Dupoiri...@pcotech.fr>
Subject Re: Importance of Javadocs
Date Fri, 08 Jul 2005 08:04:32 GMT
Ross Gardler a écrit :

> 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?

No you're not.
We can even consider to use maven to publish our documentation...

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

Mime
View raw message