Code commenting? Try Business Commenting

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.

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.