Nick Rothwell writes:
> Agreed, and I like javadoc, with a couple of caveats to its use.
> [...] javadoc coding is quite localised, and I find it tricky to
> find places to put, and refer to, architecture-level documentation (or
> textually disparate algorithms and invariants). I suspect that having
> overview documentation with HREF's into the javadoc is the way to go.
The lack of overview documentation is one of the java API doc's
biggest problems, in my opinion as a professional technical writer.
Specifically, I find myself spending too much time trying to piece
together how objects relate to each other and interact. I would guess
that, in theory, something like Rational Rose or TogetherJ could be
used to autogenerate at least a diagram.
In any event, there should be some way to automate documenting
class interactions, maybe a comment format for placing a comment right
before each external method call, that gets pulled out by javadoc and
put into some kind of class interaction overview (and maybe another
one for generating internal docs). At the very least, javadoc should
generate better cross-references. I can't begin to count how often I
have read a class description, seen "This class works with that class"
and had to dig through the index for a link to that class's docs.
But in the long run, no matter how much work you put into
automating the document maintenance, a person is going to have to
think about how a programmer would use the classes, and document it
from that perspective. One thing that every programmer I've talked to
has requested, but so few writers (particularly programmers
documenting their own work) provide, is examples. Tons and tons of
examples.
> > The second benefit of this efficiency is that the HTML (or whatever)
> > documentation is easily kept current with source-code comments,
> > simplifying one aspect of the change control management. It is important
> > that "text" documentation stay current, as it is the most accessible to
> > management.
>
> Absolutely, on both counts.
Automating and closely tying doc maintenance to the code is a
brilliant idea.
Charles wrote:
> > Again, there is no reason why there isn't a perldoc, or a cdoc, and maybe
> > there is and I haven't heard about them.
> >
> Funnily enough, there is a perldoc, called "perldoc." I've not used
> it, but I believe it ties in with Perl's ad-hoc module system.
"perldoc" is the command-line program to read the perl
documentation that comes with the distribution. The tag format is
called POD (Plain Old Documentation) and there are various converters
to easily generate HTML output (which is how the docs at www.perl.com
are maintained). For info on POD, try "perldoc perlpod" or point your
browser at http://www.perl.com/pub/doc/manual/html/pod/perlpod.html.
Btw, both commands were added to perl in 1994.
Charles wrote:
> > [CF: convoluted perl scripts? No documentation? No readable design
> > docs? But perl is open source!]
Non-sequitir. Just because other situations (closed source) hide
the problem doesn't mean they don't have the problem. My guess is
that, as the mozilla project revealed, most closed source projects are
hideously messy source code as well as open source. Debatably, open
source should be slightly less messy, since exposing your source to
the light of day is at least a slight motivator for cleaning it up.
(Don't even talk to me about project management being a motivator for
clean source...).
> My argument regarding Open Source is not the quality of the
> code, but the guarantee of availability of the source. I personally can't
> see Sun Microsystems going down the tubes anytime soon, but they are still
> in possession of the modification and update rights to the system, and can
> make wholesale changes for their particular ends, causing potential
> maintenance nightmares, although it's extremely unlikely. It's also possible
> that they could decide to restrict the licensing of future Java technology -
> also unlikely.
True. Far more pressing in my mind is the ability to fix things
that are broken. Not that this is a big issue with java, since
interoperability and distributability is such a key feature of the
product. Hence, fixing it for your own purposes doesn't guarantee the
fix will get migrated back into the general distribution, which
lessens the value of fixing it. But with more specialized products,
with open source you can fix a broken tool instead of being forced to
rewrite it from scratch. Or worse, in the case of monolithic code,
having to just limp along with the broken code until the vendor
decides it's worth fixing, if they ever do.
> > [CF: this is the bottom line. Mozilla is open source -- are you
> > surfing the web with it? No, because it's a mess right now. Open Source
> > != Good. There's lots of great open source software and also plenty of
> > open source crap.]
>
> Agreed. The open-sourcing of Mozilla was (in my view) a bit of a
> disaster because the code base was probably a disaster already.
Reportedly a rough start with extremely messy source. Also, bear
in mind that Mozilla did not start with all the source needed to make
Netscape - substantial parts were left out due to licensing issues.
Given the slowdown in browser upgrading over the last year or so, it's
problematic whether the new Mozilla will ever get a dominant share of
the market. Then again, the next version of IE will face the same
problem.
> (Oh, OK then - EMACS has got a little bloated.)
What do you mean? What more could you want from a text editor that
can also play Towers Of Hanoi, psychoanalyze you, and tell you how to bake
delicious cookies?!
> And to get back on track, for a closed system, I am very impressed
> with the Java platform (since clearly it has some good language designers at
> its heart) and it's certainly a hell of a lot more elegant and robust than
> the Microsoft stuff I'm forced to use elsewhere (products driven primarily
> by marketing rather than technical considerations).
Overall, quite impressive. Needs some work on usability levels,
inconsistencies in the way the compiler, JVM, rmic, etc, expect to be
invoked, some fairly misleading error messages, but I'm guessing Sun
isn't devoting a lot of attention there. They have a significant
investment in usability work, but they're not applying it to java or
the JDK. Then again, they're probably focusing on underlying
technology and counting on the aftermarket IDE folks to tackle
usability (which is counter to basic usability concepts, but hey).
Steven J. Owens
[EMAIL PROTECTED]
[EMAIL PROTECTED]
___________________________________________________________________________
To unsubscribe, send email to [EMAIL PROTECTED] and include in the body
of the message "signoff SERVLET-INTEREST".
Archives: http://archives.java.sun.com/archives/servlet-interest.html
Resources: http://java.sun.com/products/servlet/external-resources.html
LISTSERV Help: http://www.lsoft.com/manuals/user/user.html
