• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: WebObjects Foundation
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


References: 
 >WebObjects Foundation (From: Pascal Robert <email@hidden>)
 >Re: WebObjects Foundation (From: email@hidden)
 >Re: WebObjects Foundation (From: Pascal Robert <email@hidden>)
 >Re: WebObjects Foundation (From: "Pierce T. Wetter III" <email@hidden>)
 >Re: WebObjects Foundation (From: Andrus Adamchik <email@hidden>)
 >Re: WebObjects Foundation (From: email@hidden)
 >Re: WebObjects Foundation (From: Chuck Hill <email@hidden>)
 >Re: WebObjects Foundation (From: Mike Schrag <email@hidden>)
 >Re: WebObjects Foundation (From: Chuck Hill <email@hidden>)
 >Re: WebObjects Foundation (From: Ian Joyner <email@hidden>)

  • Prev by Date: Re: WebObjects Foundation
  • Next by Date: Code Comments
  • Previous by thread: Re: WebObjects Foundation
  • Next by thread: Re: WebObjects Foundation
  • Index(es):
    • Date
    • Thread