Re: "Tricks" of the "Trade"
Re: "Tricks" of the "Trade"
- Subject: Re: "Tricks" of the "Trade"
- From: Russell Ahrens <email@hidden>
- Date: Thu, 7 Jun 2001 18:14:34 -0400
I think of comments less as two separate stories and more as a story
with footnotes. Comments should not merely translate the code into
Natural Language; those comments get out of date very quickly. Comments
should be used to explain design decisions, describe pre- and post-
conditions, explain usage, and document thought processes that went into
a section of code. Oh, also use comments to detangle ugly code -- but
this is secondary, in my opinion.
The thing is that you need to be consistent about commenting. If you
comment sporadically, then they become less and less useful.
I wish more tools allows you to toggle the visibility of comments. The
biggest complaints I hear about comments are "comments are tedious to
write", "comments are hard to maintain", and "comments interfere with
the readability of the code". If the content of comments were a bit
more interesting (say, as described above), that takes care of the first
two; the third is best taken care of at the tool level. I've used tools
that allow you to hide blocks, or to auto-hide comments, but I can't
seem to find one on OS X, yet.
Russell Ahrens
Oink Industries
On Thursday, June 7, 2001, at 04:16 AM, Georg Tuparev wrote:
On Thursday, June 7, 2001, at 09:33 AM, Erik Thorteran wrote:
I disagree that commenting is a "deoderant" for smelly code. I use it
always, as it is not compiled. i do it just to make sure that I
understand what I was thinking an ungodly hour like now. However I do
agree with your places where you do put comments. i figure,
commenting ain't so hard, might be useful, and takes no performance
toll, so what the hell?
Let the code speak! The code IS the ultimate truth! Comments are
getting out of sync, getting obsolete. And they they slow down the
reading of the program -- imagine a book that contains two stories at
the same time - one sentence from the first story (the code) and the
next from the second story (comments). Is this fun to read?
If you don't get it, just go to Microsoft Dev Network and have some
really great time with comments ;-)
Georg Tuparev
Klipper 13
1186 VR Amstelveen
The Netherlands
Mobile: +31-6-55798196
_______________________________________________
cocoa-dev mailing list
email@hidden
http://www.lists.apple.com/mailman/listinfo/cocoa-dev