From: Bill Guindon <agorilla@...>
Date: 2005-04-28T06:26:19+09:00
Subject: Re: Comments Are More Important Than Code

On 4/27/05, Barry Sperling <barry@angleinc.com> wrote:
> 
> Dave Fayram wrote:
> 
>   But the place for whys is not in the code. The
> > code is about hows and whats.
> 
> If I have to debug some legacy code, it is because it doesn't work:
>   either because it is in error for the current parameters or the
> requirements have changed.  It saves a lot
> of time if the intent of the function is there with the code.
> 
> Unless of course you meant to attack me and the next
> > generation of coders personally. In which case, "1-2-3-4, I declare a
> > code war!" :)
> >
> 
>         No, I don't know you or your coding, so I'll attack those I do know!
> And THOSE people should
> not make things more difficult for their maintainers.  Good comments
> about the intent of functions and algorithms save time and lessen
> frustration.  We'll just have to agree to disagree and let YOUR
> maintainers have the last word.
>         Barry
> 

But can't ya do that without going to ALL CAPS?  Lighten up, it's a
friendly list (for the most part).

That said, I agree with you on "why" being an important part of the
comments, and I disagree with Dave on the following points:

> The "why" can change numerous times while the code 
> remains the same.

Personally, I think the opposite is true.  The code may change with
minor bug fixes, but "why" you wrote function x, or used algorithm z,
is not likely to change much over time.  It will change when you
switch from algorithm z to algorithm y, and the reason for doing that
is well worth commenting on.

> I can't help but believe that if a function's purpose isn't obvious
> from reading it, then either the function is poorly written or the
> reader has yet to grasp the domain.

The purpose may be obvious, but somebody who is extremely familiar
with the domain is likely to come up with a lot of the same ideas that
you did when you wrote the code.  Many of which you dismissed for one
reason or another.  Again, this goes along the lines of choice of
algorithm, but it seems to happen a lot.

When I come across somebody else's code, and think, "geeze why didn't
he just call the db library, and use the built in functions?  rolling
his own here is just asinine!"... then I start refactoring, only to
find out that the db library functions don't work in this case...
that's when I _wish_ the first coder had commented "rolled my own db
access due to db library not supporting feature xyz".

Yeah, we should both know that about 'the db library' in first place,
but this happens in the edge cases.  Nobody knows everything about any
domain, and when you run into an edge case, you're likely to spend a
lot more time trying to debug it.

btw, feel free to disagree, I won't take it personally ;)
hell, I might even learn something.

-- 
Bill Guindon (aka aGorilla)