However, while coding the algorithm, there are almost always assumptions used and conclusions reached by the programmer. You've all had that while you're coding... those thoughts like "Oh, this could be undef here" or "We must ensure that @foo is initialized before getting here" or "This will work for small lists, but blows up on big lists."
That's what belongs in the comments. Capture those thoughts, so that someone else can recreate your insights.
First, the reader of the code three months from now isn't necessarily in the same brainspace as you, and may not realize the same assumptions.
Second, in three months, you will not be in the same brainspace either. Trust me on this one.
So, comments should capture the insights and presumptions. The code should clearly express the algorithm on its own.
Just a thought, from someone who has been programming for 30 years, including re-writing code of others far too often, and pounding my head against the desk saying "WHAT were they THINKING?" {grin}
-- Randal L. Schwartz, Perl hacker
Be sure to read my standard disclaimer if this is a reply.
In reply to On commenting your code
by merlyn
in thread No Comment
by awkmonk
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |