Notebook download
Run in browser

Comments¶

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
    pass

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:
    agent.turn()
    agent.move()

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):
    pass
    # TODO: Implement pretty-printer method

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

E.g.

In [6]:

if x.safe_to_clear(): # Guard added as temporary workaround for #32
    x.clear()

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!
agent.move()
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

@double
def try_me_twice():
    pass

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