From: Dave Fayram <dfayram@...>
Date: 2005-04-28T05:44:30+09:00
Subject: Re: Comments Are More Important Than Code

Well, Barry. I can understand what you're saying, but....

> The coders ARE the ones who can document the choice of algorithms
> and explain why the function was written at all.  I've had to
> work on a lot of legacy, undocumented code and it is difficult.
> It wastes more of my time that it would have taken the writer
> to describe things well.

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. Code documentation can explain the
what, but it it shouldn't explain the why of things. The "why" can
change numerous times while the code remains the same.

There's nothing wrong with tech memos, design documents, and even
checking email logs. But the place for whys is not in the code. The
code is about hows and whats.

> Is the original coder thinking of the maintainers?  No, not
> in this "me" generation.  Not in this "obfuscated code"
> generation ( hey, if you have trouble understanding this code
> I wrote then you must not be as smart as I am! I win! )

I really don't think you can make any profound sociological
observations from observing the state of code written in the past at
your job. 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!" :)