How often do you comment?

I know that some people prefer commenting once per function in their code. I know someone who comments every single line of their code to make sure that everyone can understand it. Then there are those people who never comment except for that one comment “LOL Sucks to be you” in that one huge, confusing function. I am an extremely messy coder, with little comments in my code. What about you?

python make a distinction between documentation and comments. I try to document every function and I try to make the code clear to explain what is going on. That mostly means choosing right variable names and formating every thing not to be too nested. Too nested - looks ugly, looks ugly - needs rewrite.

Also in many places where i would normally put a comment I now put in logging statements - which turn out to work even better.

For myself, I will write a comment block at the head of each function in “”“triple quotes”"" (Python makes use of this when using the help function) that describes what the input parameters do and what the purpose of the function is. If you want to be “proper” with your function comments, the Python folks even came up with a convention to follow: http://www.python.org/dev/peps/pep-0257/.

I sparingly add comments in places where I’m doing something tricky / not straight-forward, or notes for myself of things that need to be done or fixed which get removed as I do those tasks.

I also like to go back and optimize my code, so I’ll leave myself a note for things which should not be tidied up. For example you can iterate through a dictionary using “for thing in stuff:”, but this will cause you problems if the size of the dictionary changes in the loop, so I might do something like this:

stuff = {'wolf': 'animal', 'goat': 'animal', 'cabbage': 'vegetable', 'rock': 'mineral'}
for thing in stuff.keys(): #use .keys() because some items may be removed
    if stuff[thing] == 'mineral':
        del(stuff[thing])
    else:
        print '%s is a %s' % (thing, stuff[thing])

I find the most important thing is to name your variables and functions with names that make sense, then very little explanation is needed. Using classes also helps the code be more clear.

Compare:

#loop through the characters and move them
for c in Ch:
    mvCh(c, cvel)

with

for character in game.characters:
    character.move(character.velocity)

The point is, properly written code seldom needs comments to explain itself.

  1. python code should be self-explaining
  • docstrings
  • precisely chosen names for all objects
  • separate each operation you can give a name (even if you’re sure it’s called in only one place)
  • be coherent in your coding style
  1. if it’s not, comment efficiently in the particular places
  • more comments are better than less
  • short and intelligent comments are better than long and elaborating ones

I think that comments should be kept to a minimum, only a short explanation where the code doesn’t speak for itself.

sure, but that point is under 2, which applies only if 1. is undoable

but you could rephrase my statement with:
if you’re unsure whether you should put a comment line in or not it’s most probably better to do it.