Source Documentation

[Brill Pappin <br...@jmonkey.com>]

I just checked out the current version of the classes from the anon CVS
server...
I have to say, the commenting in most of the files is really bad. and makes
it impossible to generate any useful JavaDocs from the source files...

Commenting the method before its even implemented really makes you think
about what you are doing...

I suggest that proper javadoc comments should be part of the coding
guidlines, and actually be written...
that means that at least when something new goes in, the developer should
take 20 mins. and add the JavaDoc comments to the file.

This source is going to be around for a *long* time, and it will be
invaluble to some poor soul, 5 years from now (if not right this instant,
like myself), who comes in half way and needs to understand whats going
on... not to mention its value to the person who wrote the code, when they
have to go back to it, and figure out what etheral state their mind was in
at the time.

Truth be known, I expected much more from such a well rounded, and
experianced development group.

- Brill Pappin
  www.jmonkey.com

Re: Source Documentation

["Anil K. Vijendran" <An...@eng.sun.com>]

Brill, Craig et al.

We hear ya :-)

Internal documentation is one of those things that got slipped a bit given some
crazy schedules we've had to deal with this year.  Some internal re-org of this
stuff and the ApacheCon talk on Tomcat internals are intended to serve as
motivation to clean up and document some of this. It'll happen soon :-)

"Craig R. McClanahan" wrote:

> Coming from developing in the Apache JServ project (check the high quality of
> source code comments in that code base to see what I was used to), I have been
> needling the Sun folks that we need to bring Tomcat's code up to open source
> quality standards.  :-)
>
> More seriously, I agree with you that the internal code documentation is
> extremely important.  Given that they didn't necessarily plan on writing
> anything but a closed source reference implementation, I can be a little bit
> sympathetic about how it came to be like this, but that was then and this is
> now.  I've suggested that Sun task some of the original developers to document
> the code, which would be much more efficient than anyone else trying to reverse
> engineer the thinking process.  Failing that, it's time to start digging in and
> documenting as we go.

--
Peace, Anil +<:-)

Re: Source Documentation

[Brill Pappin <br...@jmonkey.com>]

Well, digging in and doing it ourselves is what's needed, I may be able to
help some...
I'm an experienced Java developer (including servlet and HTTP server) and
wouldn't mind putting some time in.

Actually, I'm surprised that the original code wasn't commented... but I
guess I shouldn't be, knowing Sun :)

- Brill Pappin
  www.jmonkey.com

----- Original Message -----
From: Craig R. McClanahan <cm...@mytownnet.com>
To: <ge...@jakarta.apache.org>
Sent: Friday, November 19, 1999 8:17 PM
Subject: Re: Source Documentation


> Brill Pappin wrote:
>
> > I just checked out the current version of the classes from the anon CVS
> > server...
> > I have to say, the commenting in most of the files is really bad. and
makes
> > it impossible to generate any useful JavaDocs from the source files...
> >
> > Commenting the method before its even implemented really makes you think
> > about what you are doing...
> >
> > I suggest that proper javadoc comments should be part of the coding
> > guidlines, and actually be written...
> > that means that at least when something new goes in, the developer
should
> > take 20 mins. and add the JavaDoc comments to the file.
> >
> > This source is going to be around for a *long* time, and it will be
> > invaluble to some poor soul, 5 years from now (if not right this
instant,
> > like myself), who comes in half way and needs to understand whats going
> > on... not to mention its value to the person who wrote the code, when
they
> > have to go back to it, and figure out what etheral state their mind was
in
> > at the time.
> >
> > Truth be known, I expected much more from such a well rounded, and
> > experianced development group.
> >
> > - Brill Pappin
> >   www.jmonkey.com
> >
>
> Coming from developing in the Apache JServ project (check the high quality
of
> source code comments in that code base to see what I was used to), I have
been
> needling the Sun folks that we need to bring Tomcat's code up to open
source
> quality standards.  :-)
>
> More seriously, I agree with you that the internal code documentation is
> extremely important.  Given that they didn't necessarily plan on writing
> anything but a closed source reference implementation, I can be a little
bit
> sympathetic about how it came to be like this, but that was then and this
is
> now.  I've suggested that Sun task some of the original developers to
document
> the code, which would be much more efficient than anyone else trying to
reverse
> engineer the thinking process.  Failing that, it's time to start digging
in and
> documenting as we go.
>
> Craig McClanahan
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>

Re: Source Documentation

["Craig R. McClanahan" <cm...@mytownnet.com>]

Brill Pappin wrote:

> I just checked out the current version of the classes from the anon CVS
> server...
> I have to say, the commenting in most of the files is really bad. and makes
> it impossible to generate any useful JavaDocs from the source files...
>
> Commenting the method before its even implemented really makes you think
> about what you are doing...
>
> I suggest that proper javadoc comments should be part of the coding
> guidlines, and actually be written...
> that means that at least when something new goes in, the developer should
> take 20 mins. and add the JavaDoc comments to the file.
>
> This source is going to be around for a *long* time, and it will be
> invaluble to some poor soul, 5 years from now (if not right this instant,
> like myself), who comes in half way and needs to understand whats going
> on... not to mention its value to the person who wrote the code, when they
> have to go back to it, and figure out what etheral state their mind was in
> at the time.
>
> Truth be known, I expected much more from such a well rounded, and
> experianced development group.
>
> - Brill Pappin
>   www.jmonkey.com
>

Coming from developing in the Apache JServ project (check the high quality of
source code comments in that code base to see what I was used to), I have been
needling the Sun folks that we need to bring Tomcat's code up to open source
quality standards.  :-)

More seriously, I agree with you that the internal code documentation is
extremely important.  Given that they didn't necessarily plan on writing
anything but a closed source reference implementation, I can be a little bit
sympathetic about how it came to be like this, but that was then and this is
now.  I've suggested that Sun task some of the original developers to document
the code, which would be much more efficient than anyone else trying to reverse
engineer the thinking process.  Failing that, it's time to start digging in and
documenting as we go.

Craig McClanahan