tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Craig R. McClanahan" <Craig.McClana...@eng.sun.com>
Subject Re: Javadoc !!!
Date Tue, 25 Jul 2000 17:52:02 GMT
Matthew Dornquast wrote:

> re>Nick: <rant><snip/></rant>
>
> Ironically, I found myself missing design docs more than java doc when
> studying tomcat.
>
> High level pictures are nice, two pictures would solve most of the issues:
>
> 1.  High level static object model that shows relationships between major
> parts of tomcat.  (Almost at the package level)
> 2.  High level sequence diagram on a "happy path" through tomcat showing
> dynamic relationship of objects illustrated in step 1.
>
> The code was readable, although sparse (Heck, barren) in comments.  It was
> the "flow" that was hardest to disern.
> How did I get here?  Where am I going?  How do I intercept this valve? 8-)
>

One thing that will help (when I get to it) will be HTML-izing the Catalina
Architecture Overview talk that I've now given at JavaOne and a couple of the
O'Reilly conventions.  That will provide the pictures, but without the words
it's still incomplete.

>
> <rant>
> What bugged me even more was the arbitrary use of spaces and tabs for
> indentation.  Very inconsistent!
> </rant>
>

Just set your tab stops to eight (like any self-respecting developer would :-)
and they will look wonderful!  NOTE: the tab width issue is discussed in the
coding conventions document pointed at on the web site.

(Emacs's Java mode does most of the leading space generation for you when you
press tab).

>
> A beautifier behind the CVS checkin event can work wonders for code
> consistency.  JIndent has a great functionality and even stubs in java docs
> for those that forget. :)
>

I can tell you from experience that these kinds of things create CVS checking
reports (logging the differences) that are virtually impossible to read, and
make it very difficult to tell what code was changed deliberately in this patch
and what code was just rearranged for you.

>
> -Matthew
>

Craig



Mime
View raw message