

Minimal Advice to Undergrads on Programming - antiform
http://cscs.umich.edu/~crshalizi/weblog/593.html

======
jackowayed
Does anyone comment to that degree?

My general policy is to follow the "Use meaningful names" policy and use that
as the commenting. The meaningful names of the function give you an idea of
what they do and what side effects they have. The meaningful names of the
parameters tell you what they do.

Maybe it's not a perfect system, but I think it's a happy medium between
eating up a lot of time commenting and having totally unreadable code

~~~
jbjohns
Personally I try to only comment the "why", as this is what you can't figure
out from code. Having a good revision control system allows you to log the
"why" why even better.

Comments themselves have, especially when you have lots of them, a really high
danger of not getting updating and therefor becoming a liability.

When you write code you are supposed to write (1) the tests, (2) the
documentation and (3) the actual code. Only one of those can make what you
want to happen happen, and one of those is annoying if it doesn't get fixed
but one of those wont do anything if completely wrong. At least not right
away.

