Re: WebObjects Foundation
Re: WebObjects Foundation
- Subject: Re: WebObjects Foundation
- From: Ian Joyner <email@hidden>
- Date: Wed, 16 Aug 2006 11:55:29 +1000
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).
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.
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 as well.
Ian
_______________________________________________
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