7.1 Comments
Contents
7.1 Comments#
Estimated time for this notebook: 15 minutes
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
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.
Prefer “in language” comments to comments proper, if we can#
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
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
we have used comments to make the code readable.
Why not make the code readable instead?
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 are unpublishable#
# 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
# This is how you define a decorator in python
# See https://wiki.python.org/moin/PythonDecorators
def double(decorated_function):
# Here, the result function calls the decorated_function
# twice, first on the entry input and then again on the
# output of that
# 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
Are comments always helpful?#
Some authors argue that comments can be dangerous, as they can disincentivise us from trying harder to use variable names and function names to discribe the 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
This is definitely taking things too far, but there’s a little grain of truth in it:
Comments which are obvious#
Try to use comments to explain why the code does, not just repeat the code in a comment.