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.

3: Getting Help

Book ref: Project 1 (pg 24ff)

Python 2.7: Same

See also: Python 3/Project 4 post

Python 3 comes with its own help facility. To use it, you simply type:

>>> help()

Welcome to Python 3.4's help utility!

If this is your first time using Python, you should definitely check out
the tutorial on the Internet at http://docs.python.org/3.4/tutorial/.

Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules.  To quit this help utility and
return to the interpreter, just type "quit".

To get a list of available modules, keywords, symbols, or topics, type
"modules", "keywords", "symbols", or "topics".  Each module also comes
with a one-line summary of what it does; to list the modules whose name
or summary contain a given string such as "spam", type "modules spam".

Note: you have to include the brackets help(). Just help won’t work:

>>> help
Type help() for interactive help, or help(object) for help about object.

As the text says, once you’re in the help service. To leave you type quit and press Enter.

You can get help on a specific feature by typing that feature at the help> prompt. If I type print and press Enter it tells me:

Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

On my system, this is not printed below the Python prompt. Rather, it is specially formatted (by a thing called a “pager”). To get back to the help> prompt I have to press the Q key.

The next place to look for help is in Python’s online documentation. That may be a little intimidating at the moment, but just go to it slowly. You’ll start to learn your way around it. One of the problems with learning Python 3 is that it is being continuously improved, so with each new version (I have version 3.4 installed, but the most recent version as at the time I am writing this is version 3.6) the documentation changes. Ideally, you’ll chose the version of the documentation that matches the version of Python you have installed on your computer. The good news is that for the stuff you’re learning things are unlikely to change for the foreseeable future.

Python 2.7 Notes: the same help facility is in Python 2.7.

3: Import this!

Book ref: Project 3 (pg 78ff)

Python 2.7: Same

>>> import this

Do it to learn something about the Zen of Python.