Comments

Please open notebook rsepython-s4r3.ipynb

Let’s import the context for this chapter.

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. In the beginning you may comment a lot to aide your own understanding, but as you become more experienced they should become more purposeful.

There are a number of ways in which comments can be unhelpful or help mask poorly designed code.

Comments which are obvious

counter=counter+1 # Increment the counter
for element in array: # Loop over elements
    pass

Where the code is obvious, comments are unnecessary.

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(object):
   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

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.

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

is OK. 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!

These add very little value, would be better removed or replaced by more meaningful comments.

Comments which are unpublishable

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

These are unprofessional and should not feature in your code base.

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 forms a closure over
   # the decorated function
   def result_function(input):
       return decorated_function(decorated_function(input))
   # 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.

For example:

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

Next: Reading - Refactoring