marc@dumbcat.sf.ca.us (Marco S Hyman) (06/24/91)
In article <1991Jun23.025529.7749@netcom.COM> jls@netcom.COM (Jim Showalter) writes: > I regard most comments as > an admission of failure and/or a design flaw in the implementation > language. ARGGGGHHHHH. (Caution, button being pushed :-) If this is the case then you're reading/writing the wrong kind of comments. Agreed, comments that just explain what's being done contribute nothing. It's the old assembler comment syndrome: sub A,A ; clear accumulator The comment adds nothing. However, comments that explain _why_ something is being done can aid understanding. Something like: // use an inline sort here as there will never be more than // five items to sort. A comment like this can save much time 8 months down the road when someone else is making changes, optimizing, whatever. If you forget things fast (I do!) then the comments can help you remember when you're looking at your own code. This is language independent. // marc -- // home: marc@dumbcat.sf.ca.us pacbell!dumbcat!marc // work: marc@ascend.com uunet!aria!marc
jls@netcom.COM (Jim Showalter) (06/25/91)
>However, comments that explain _why_ something is >being done can aid understanding. We're in violent agreement. When I said I regarded most comments as superfluous, I was talking about the paraphrasing comments and the comments that work around missing language features. I completely agree with you that design comments are valuable. Sadly, these are the minority of comments in much of the code that is inflicted on me. -- *** LIMITLESS SOFTWARE, Inc: Jim Showalter, jls@netcom.com, (408) 243-0630 **** *Proven solutions to software problems. Consulting and training on all aspects* *of software development. Management/process/methodology. Architecture/design/* *reuse. Quality/productivity. Risk reduction. EFFECTIVE OO usage. Ada/C++. *