You are here: Home > Dive Into Python > Your First Python Program > Documenting Functions | << >> | ||||
Dive Into PythonPython from novice to pro |
You can document a Python function by giving it a doc string.
Example 2.2. Defining the buildConnectionString Function's doc string
def buildConnectionString(params): """Build a connection string from a dictionary of parameters. Returns string."""
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 can use them anywhere, but you'll see them most often used when defining a doc string.
Triple quotes are also an easy way to define a string with both single and double quotes, like qq/.../ in Perl. |
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. I know you've heard this in every programming class you've ever taken, but Python gives you an added incentive: 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. This can be incredibly helpful, but it's only as good as the doc strings you write. |
Further Reading on Documenting Functions
- PEP 257 defines doc string conventions.
- Python Style Guide discusses how to write a good doc string.
- Python Tutorial discusses conventions for spacing in doc strings.
<< Declaring Functions |
| 1 | 2 | 3 | 4 | 5 | 6 | |
Everything Is an Object >> |