Re: WebObjects Foundation
Re: WebObjects Foundation
- Subject: Re: WebObjects Foundation
- From: Chuck Hill <email@hidden>
- Date: Tue, 15 Aug 2006 19:09:30 -0700
On Aug 15, 2006, at 6:55 PM, Ian Joyner wrote:
On 16/08/2006, at 11:18 AM, Chuck Hill wrote:
On Aug 15, 2006, at 6:10 PM, Mike Schrag wrote:
The last time I looked at the WOLips code, it was, um, er, not
very well commented.
comments ... comments ... nope, haven't heard of em.
LOL
Real developers don't have time to comment!
Agree absolutely. I hardly ever put comments in my source (note I
avoid the word 'code'), but my source is well documented, as I know
is Chuck's because he makes liberal use of programming by contract
(although in Java, the best you can do is structured comments,
which doesn't have the advantage of real error checking that a real
language would have).
I think we need to discriminate here between comments inside methods
and comments _about_ methods. Comments inside of a method usually
indicate bad code, obscurely written code at the very least.
Comments about methods, parameters, return values etc. (i.e. JavaDoc
comments) are a different story. Such API comments / documentation
are mandatory for all but the most obvious methods, IMHO. Without
usage and design docs is it hard to know what some other developer
intended.
Good source is readable without comments, and comments should be
restricted to those bizarre cases where something didn't quite work
the way expected, or you chose this particular way for some reason.
Otherwise comments should not be used, especially to 'decode' your
'code'.
Type parameters (generics) also provide good documentation, since
it documents what type a collection is used to store. But it goes
further, letting the compiler generate errors early if you try to
put something else in, rather than later at run time. Now
hopefully, all I have to do is globally replace all my /*[ for <
and ]*/ for > and I can turn all those dead comments into useful
live documentation.
On the other hand, I don't like the project-management people who
go around trying to make out that documentation is something
external to 'code' and that a well-documented program is something
with a completely parallel document stating everything that you
should be able to read in the 'source', be it text or UML-style
diagrams. That is not to say that some level of external
architectural documentation is not necessary. But as usual, less is
better.
Yes. A picture is worth a thousand words but a thousand pictures is
just bewildering.
Gee, I know an innocent joke, and I launch into a whole long-winded
epistle, but hey you guys are coming from the right direction here!
LOL
Chuck
--
Practical WebObjects - for developers who want to increase their
overall knowledge of WebObjects or who are trying to solve specific
problems. http://www.global-village.net/products/practical_webobjects
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden