Let's import first the context for this chapter.

In [1]:
from context import *

Why comment?

  • You're writing code for people, as well as computers.
  • Comments can help you build code, by representing your design
  • Comments explain subtleties in the code which are not obvious from the syntax
  • Comments explain why you wrote the code the way you did

Bad Comments

"I write good code, you can tell by the number of comments."

This is wrong.

Comments which are obvious

In [2]:
counter = counter + 1 # Increment the counter
for element in array: # Loop over elements

Comments which could be replaced by better style

The following piece of code could be a part of a game to move a turtle in a certain direction, with a particular angular velocity and step size.

In [3]:
for i in range(len(agt)): #for each agent
    agt[i].theta += ws[i]     # Increment the angle of each agent
                              #by its angular velocity
    agt[i].x += r * sin(agt[i].theta) #Move the agent by the step-size
    agt[i].y += r * cos(agt[i].theta) #r in the direction indicated

we have used comments to make the code readable.

Why not make the code readable instead?

In [4]:
for agent in agents:

class Agent:
    def turn(self):
         self.direction += self.angular_velocity;
    def move(self):
        self.x += Agent.step_length * sin(self.direction)
        self.y += Agent.step_length * cos(self.direction)

This is probably better. We are using the name of the functions (i.e., turn, move) instead of comments. Therefore, we've got self-documenting code.

Comments vs expressive code

The proper use of comments is to compensate for our failure to express yourself in code. Note that I used the word failure. I meant it. Comments are always failures.

-- Robert Martin, Clean Code [UCL library].

I wouldn't disagree, but still, writing "self-documenting" code is very hard, so do comment if you're unsure!

Comments which belong in an issue tracker

In [5]:
x.clear() # Code crashes here sometimes
class Agent(object):
    # TODO: Implement pretty-printer method

BUT comments that reference issues in the tracker can be good.


In [6]:
if x.safe_to_clear(): # Guard added as temporary workaround for #32

is OK. And platforms like GitHub will create a link to it when browsing the code.

Comments which only make sense to the author today

In [7]:
agent.turn() # Turtle Power!
agents[:]=[]# Shredder!

Comments which are unpublishable

In [8]:
# Stupid supervisor made me write this code
# So I did it while very very drunk.

Good commenting: pedagogical comments

Code that is good style, but you're not familiar with, or that colleagues might not be familiar with

In [9]:
# This is how you define a decorator in python
# See https://wiki.python.org/moin/PythonDecorators
def double(decorated_function):
    # Here, the result function forms a closure over 
    # the decorated function
    def result_function(entry):
        return decorated_function(decorated_function(entry))
    # The returned result is a function
    return result_function

def try_me_twice():

Good commenting: reasons and definitions

Comments which explain coding definitions or reasons for programming choices.

In [10]:
def __init__(self):
    self.angle = 0 # clockwise from +ve y-axis
    nonzero_indices = [] # Use sparse model as memory constrained