4 ms·

Code commenting? Try Business Commenting

11 points by hhm 18y ago

gm 18y ago
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 18y ago
  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 18y ago
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.

11 points by hhm 18y ago

gm 18y ago

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 18y ago
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 18y ago

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.