Charles,
Good points you make, all of them. (And tangential to the technical threads
of this list, but probably more relevant at the design/politics level.)
> As an outside contractor, I certainly don't want to place undo criticism
> on outside contractors!
>
Agreed (also as a contractor), although in the past I've been called
in to fix problems caused by dreadful work by previous contractors.
> javadoc provides a tool that helps two major problems with project
> handovers. The first is that the original developers frequently have to
> document their code twice. They must document with in-line comments and
> with a text format such as Microsoft Word or HTML. With javadoc,
> sourcecode comments do "double duty," saving developers a lot of effort
> during the cleanup of a project.
>
Agreed, and I like javadoc, with a couple of caveats to its use.
Firstly, putting in source code comments during cleanup is not a good way to
go (unless you're trying to make sense of some uncommented code left by
someone else, in which case it should never have made it through any kind of
walkthrough); much better to javadoc while coding, while the ideas are
fresh. Secondly, 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 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.
> 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.
To your annotations on Tim O'Reilly's tale (and I also find Slashdot
an illuminating read):
> [CF: convoluted perl scripts? No documentation? No readable design
> docs? But perl is open 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.
> [CF: rewrite for UNIX? What does that mean? We are about to enter
> the 21st century and people are writing code that costs hundreds of
> thousands of dollars to port? Java may have occaision porting problems,
> but would it ever cost that much?]
>
I would hope not. It sounds as if this company had been given
wholesale Microsoft brain transplants and had totally spot-welded themselves
to Win32 and NT.
> [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. I swear by
the open source tools that I use for general development (centred around the
monolithic GNU EMACS, plus all the shell tools, makefiles and the like)
because these were built to solve specific problems by the people who needed
to use them. (Oh, OK then - EMACS has got a little bloated.)
Again, my argument for open source was that control is not vested in
one organisation. Arguments about quality and so on are a different issue.
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).
___________________________________________________________________________
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
