Contents

Let’s import first the context for this chapter.

from context import *


Why comment?¶

• You’re writing code for people, as well as computers.

• Comments explain subtleties in the code which are not obvious from the syntax

• Comments explain why you wrote the code the way you did

The Pseudocode Programming Process¶

Start by writing a program in all comments:

# To find the largest element in an array
# Set up a variable to track the largest so far
# Loop over every element
# For each element, is it bigger than the previous biggest?
# If so, it's the new biggest
# At the end, the biggest so far, is the biggest overall


One by one, replace these with the equivalent in code

# To find the largest element in an array
def largest(data):
# Set up a variable to track the largest so far
biggest_so_far = 0
# Loop over every element
for datum in data:
# For each element, is it bigger than the previous biggest?
if datum > biggest_so_far:
# If so, it's the new biggest
biggest_so_far = datum
# At the end, the biggest so far, is the biggest overall
return biggest_so_far

largest([0,1,3,6,2,5,3])

6


Then, remove only those comments that are now extraneous (see below for examples of extraneous comments)

# To find the largest element in an array
def largest(data):
# Set up a variable to track the largest so far
biggest_so_far = 0
for datum in data:
# For each element, is it bigger than the previous biggest?
# If so, it's the new biggest
if datum > biggest_so_far:
biggest_so_far = datum
return biggest_so_far


Who are you writing for?¶

• By far the most likely person who will read your code/comments is yourself, maybe in a week’s time, or maybe in six months time.

• Second most likely person in most cases, is someone in your team, or someone else who will probably have a roughly similar level of expertise, and be trying to do a similar thing.

• Write comments with this in mind - try to help the person reading the code to understand what you did and why.

More comments doesn’t necessarily mean better - here are some examples of comments that don’t really help the reader understand the code any better. If we can, it’s nice to find ways to put our description of what the code does inside the code, instead of as comments. Then, when the code changes, the ‘comments’ stay in sync, beause they’re part of the code.

For example, we can use a variable name or a function name, to hold what would have been in a comment. Here, instead of a comment and a one-word function name, we’ve made a longer function name.

def largest_element_in_array(data):
# Set up a variable to track the largest so far
biggest_so_far = 0
for datum in data:
# For each element, is it bigger than the previous biggest?
# If so, it's the new biggest
if datum > biggest_so_far:
biggest_so_far = datum
return biggest_so_far


Try to use comments to explain why the code does, not just repeat the code in a comment.

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.

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


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 which belong in an issue tracker¶

x.clear()  # Code crashes here sometimes

class Agent:
pass
# TODO: Implement pretty-printer method


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

E.g.

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¶

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


# Stupid supervisor made me write this code
# So I did it while very very drunk.


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

# 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


Great commenting: reasons and definitions¶

Comments which explain coding definitions or reasons for programming choices.

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