Beginning Python Tutorial (Part 9)

Documenting Python Code

Some of this information is borrowed from Dive Into Python, a free Python programming book for experienced programmers. Other info is from the Python Style Guide.

You can document a Python function by giving it a doc string.

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.

    Returns string."""

As noted previously, triple quotes signify a multi-line string. Everything between the start and end quotes is part of a single string, including carriage returns and other quote characters. You'll see them most often used when defining a doc string.

Everything between the triple quotes is the function's doc string, which documents what the function does. A doc string, if it exists, must be the first thing defined in a function (that is, the first thing after the colon).

You don't technically need to give your function a doc string, but you always should; the doc string is available at runtime as an attribute of the function. Many Python IDEs use the doc string to provide context-sensitive documentation, so that when you type a function name, its doc string appears as a tooltip.

From the Python Style Guide:

The doc string of a script should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a doc string should document the script's function and command line syntax, environment variables, and files. Usage messages can be fairly elaborate (several screenfuls) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.

There are two forms of doc strings: one-liners and multi-line doc strings. One-liners are exactly that: information that doesn't need a lot of descriptive text to explain what's going on. Triple quotes are used even though the string fits on one line to make it easy to later expand it. The closing quotes are on the same line as the opening quotes, since it looks better. There's no blank line either before or after the doc string. The doc string is a phrase ending in a period. It prescribes the function's effect as a command ("Do this", "Return that"), not as a description: e.g. don't write "Returns the pathname ..."

Example:

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    #...

Multi-line doc strings start out just like a single line doc string. The first line is a summary but is then followed by a blank line. After the blank line more descriptive discussion can be made. The blank line is used to seperate the summary from descriptive info for automatic indexing tools. They will use the one-line summary to create a documentation index, allowing the programmer to do less work.

When continuing your doc string after the blank line, make sure to follow the indentation rules for Python, i.e. after the blank line all of your doc string info is indented as far as the initial triple-quote.

More info from the Python Style Guide:

The doc string for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's doc string.)

The doc string for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

The doc string for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the doc string). The class constructor should be documented in the doc string for its __init__ method. Individual methods should be documented by their own doc string.

If a class subclasses another class and its behavior is mostly inherited from that class, its doc string should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).

Python is case sensitive and the argument names can be used for keyword arguments, so the doc string should document the correct argument names. It is best to list each argument on a separate line, with two dashes separating the name from the description

If you've made it this far, I'll help you out and summarize what you just learned. Python has a documentation feature called doc string that allows you to use comments to create self-documenting source code. Several Python IDE's, such as SPE, can use these doc strings to create a listing of your source code structures, such as classes and modules. This makes it easier on the programmer since less work is required when you create your help files and other program documentation. Documentation indexers can pull the doc strings out of your code and make a listing for you, or you could even make your own script to create it for you.

However, the only way to harness the power of doc strings is to follow the style rules Python expects, meaning you have to use triple-quotes, separate your summary line from the full-blown description, etc. You can document your Python code without following these rules but then it's up to you to create a help file or whatever.

Not only will it make your life easier when you finish your project, but it also makes your code easier to read and follow. (Wish the people at my work could learn how to document their code. Even just a few comments explaining what a function does would help. :) )