Re: "Tricks" of the "Trade"
Re: "Tricks" of the "Trade"
- Subject: Re: "Tricks" of the "Trade"
- From: jgo <email@hidden>
- Date: Sat, 16 Jun 2001 20:15:14 -0700
>
Georg Tuparev <email@hidden> 2001 June 07 09:25:44 +0200 wrote:
>
> On Thursday, 2001 June 7, at 02:15, Erik Thorteran wrote:
>
> 5. Comment code, always. You may notice that the aforementioned
>
> single line of code has no comments, this is one of the
>
> reasons it was such a pain to debug.
>
>
Hmmm. Here is a quote from Martin Fowler's Refactoring book:
>
"The reason we mention comments here is that comments often are
>
used as a deodorant [for smelly code - gt]. It's surprising
>
how often you look at trickly commented code and notice that
>
the comments are there because the code is bad"
>
>
My advise: do not use comments, but use proper method and variable
>
names. One of the beauties of ObjectiveC is that (similar to
>
Smalltalk) it is a self commenting language (if used properly)...
That's what they said about COBOL (gobble gobble).
The trouble is that what seemed clear & clean & elegant when
you first wrote it often seems opaque & smelly & convoluted
a month or a year later... and if you're trying to figure
out someone else's code -- someone from a different school
with different "proper methods & variable names" -- it's
much worse.
My advice: use comments. Use them when you think they're needed.
Use them when you think they're not needed. Use them to explain
the obvious. Use them to record the evolution of the design and
the implementation. Use them to let that newbie programmer who
will be hired in 3 years figure out what the heck you were doing
so that in hir first week s/he can repair the bug you didn't
notice you'd designed in. Use them to spot those bugs before
you write them in by requiring yourself to state clearly what
it is you are trying to do with what.
I'm not quite of the school that believes you should write such
detailed documentation that when you were done the code would be
there as a side-effect. (See A.E. van Vogt's books on "null-A"
:B-)
John G. Otto Nisus Software, Engineering
www.infoclick.com www.mathhelp.com www.nisus.com software4usa.com
EasyAlarms PowerSleuth NisusEMail NisusWriter MailKeeper QUED/M
My opinions are probably not those of Nisus Software, Inc.