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