

Code commenting? Try Business Commenting - hhm
http://blogs.msdn.com/avip/archive/2008/07/25/code-commenting-try-business-commenting.aspx

======
gm
I tink it's dumb to remove the comments from code, although I agree with
making symbol names more meaningful.

In the original post, the comment

// square root of n with Newton-Raphson approximation

Is removed and replaced with the improved function name of
SquareRootApproximation(). A good improvement to the code, to be sure, but you
lose the information about the code implementing a "Newton-Raphson
approximation." The author just glosses over that.... Of course somepne will
come back 3 years later and ask themselves, "which algorithm is this?"

So, to tie it back to the topic about business comments, yes, business
comments should be there in the code as well. It always helps, and it helps
locate customizations that, at first reading do not make sense.

So, comments or better-written code? Both. Redundancy is really good when it
contributes to making code more clear.

~~~
moss
It's good until you rewrite the function to use a different algorithm, but
forget to update the comment. After that, it's a confusing contradiction that
will slow down anyone who tries to read the code.

If the code is genuinely hard to follow without it, it's probably still worth
leaving a comment, but recognize that there are real costs to balance out the
benefits of commenting.

------
sh1mmer
I can't agree with this enough.

There are many reasons why code can be obtuse, from first pass un-refactored
code, to performance constraints. Comments are totally essential and
explaining why code was written in a particular way is helpful.

However Ari's point I think is even more critical. The code was written to
solve some business problem, whatever it looks like it needs to continue to
deal with that problem. I particularly like the pointer to a requirement
ticketing system (Y! use bugzilla for this). That way you can see all the
previous discussion around the business requirement without sullying the
codebase.

I can't +1 this post enough.

