Question regarding commenting code
J.Jacob
joost_jacob at hotmail.com
Thu Sep 6 15:22:19 EDT 2001
A very simple rule we found useful is this:
"only comment variables"
Meaning you only explain the "nouns" in your code. The other code
(the "verbs") should speak for themselves.
If you have a really complex function you can also put an "algorithm"
comment block after the function header, or a "usage" block after a
complex class header.
Other than that it should be enough to describe what a variable does
in your code, and maybe also what it means and why it is used.
We had good experiences using this comment-style-rule in a team.
More information about the Python-list
mailing list