On 16/08/2006, at 12:24 PM, Dov Rosenberg wrote: Like usual the threads have been hijacked from their original purpose.
Good point, I'll move the discussion here. On 16/08/2006, at 12:09 PM, Chuck Hill wrote:
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.
I agree, but anything that is not obvious should be rewritten (ie documented), not in retrospect commented. In good class design, the API should be obvious, and I think that the routine names and parameter names should be expressive enough (and there should hardly ever be reason for more than two or three arguments). My methods all tend to be short, around five lines (although I have written some long text search routines lately: key x partial x exclude -> Set, which have branches for whether search is partial word or to exclude the word, but the API is still rather obvious). WO encourages short methods too.
For such a reason, I avoid JavaDoc, which I don't like for another reason, being that when I am looking at the source, the comments are unreadable because of the HTML markup in it. Even if that is not there I don't like all the @@ garbage used by JavaDoc. (Now the language that does design by contract is structured enough to generate nice documentation without that gloop. Flat and Short are much better at generating HTML or other docs without polluting the source code.)
The idea behind JavaDoc is good, but it's a horrible implementation, and I'm not sure I want to have to go to a Web browser to look at documentation for code I'm working on. Without usage and design docs is it hard to know what some other developer intended.
Design docs, yes, but I think usage docs should be automatically generated from code (which where JavaDoc gets a good idea wrong).
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
|