3: Comments


Book ref: Project 4 (pg 95ff)

Python 2.7: Same

In this post you’re going to learn how to write code that Python ignores. Does that seem odd?
What would be the point of writing code and then deliberately not using it? It turns out that
there are two important times when you would prefer that Python did not execute your code:

  • comments, which you’ll be learning about in this post; and
  • debugging, which you’ll learn about later.

There are two main ways to make a comment in Python. The first is to put a hash mark (#) in
front of the comment. Here is an example:

>>> # This code does nothing
>>> 

Hopefully you can see that the text with the # in front of it was ignored by the Python interpreter.
You can see that this is the case by trying it without the # and seeing what happens.

>>> This code doesn't do anything
SyntaxError: invalid syntax
>>>

Without the # Python tries to run the comment as if it was Python code – and, of course, fails.

Aside
Whenever you are not sure about how something works in Python open up a Python console and give it a try and see what happens. Often, if there is a mistake Python will give you an error message that will help you work out how to do it correctly.

The second way of making a comment is by putting triple double quotes (“””) on both sides of the comment. Like this:

>>> """ This code does nothing"""
" This code does nothing"

You can see from the print out that while the # comment above really did nothing, this code has done something – it’s printed out the content of the comment. It did this because it has created a string literal but hasn’t given it a name. In practical terms though, the code has done nothing. The only reason that it has printed out the comment is because you are running the Python console. If you ran this from a file (see the python idle post for more info), nothing would be printed.

Aside
Technically the other ways of making string literals will work as comments, but the accepted way of doing it is by using triple double quotes.

What are comments for?

You use comments mainly to explain to someone else what your code is doing (try to imagine that you’re trying to explain your code to your parents). As such, comments should explain why, not describe how. This is a bad comment:

>>> a = a*2 # multiply a by 2

This is a bad comment because it simply repeats in words what the code is doing. Anybody reading the code can work that out for themselves, so it’s not adding anything. It is better to explain why the code is doing whatever it is doing.

This might be a better comment:

>>> a = a*2 # the next section of code below needs a to be even

In this code, the comment is explaining why a is being multplied by 2. That is, to make sure that a is an even number. We can’t tell from this why it’s important for a to be even, but we can tell why the code is doubling a.

Explanatory comments like these turn out to be very important. That’s because you often need to come back to code that you’ve written a long time ago (like last month). If you don’t have comments explaining why the code is doing what it’s doing it can be very difficult to understand what is going on. So, it’s difficult to reuse the code for other projects, or two tweak the code to cater to new circumstances.

In general, comments are a good thing. The more comments the better. That said, you can get too much of a good thing and there is a point where you have too many. Exactly how many comments are too many is hard to say. Best way is to write comments and get a feel for it yourself.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: