Re: Problems retaining what I study

I used to work for a software vendor whose policy was "*no comments in code*
".
Usually I'm a real documentation kind of guy. So I was a bit shocked at this 
policy, to say the least. And this job was writing C code which doesn't have 
a reputation for self-documentation. After working there for awhile, I 
gradually began to see the wisdom of their policy. Consider these points:
 - Comments can be a crutch. If a programmer is forced to rely solely on the 
code, then you tend to make the code more self-documenting. Perhaps instead 
of selecting "A", "B" and so on for variable names, you carefully select 
meaningful names. Or write the code in a straightforward manner rather than 
dazzling with arcane constructions.
 - Out-of-date comments can be misleading. People often modify code but fail 
to modify the comments.
 - Most comments are superfluous, of the variety "the following line sums 
the values of A and B and stores the result in C", followed by C = A + B. 
Having 7 lines of comment per line of code can end up obscuring the code.
 Dennis Williams

Other related posts: