Close

MPHY0021: Research Software Engineering With Python

Home

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 explain subtleties in the code which are not obvious from the syntax
• Comments explain why you wrote the code the way you did

"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