Строки документации Python

Документация чрезвычайно важна не только для того, чтобы сообщить другим людям, какова цель функции / класса / метода / модуля, но и для вас самих.

Когда вы вернетесь к своему коду через 6 или 12 месяцев, вы можете не вспомнить все знания, которые храните в своей голове, и читать код и понимать, что он должен делать, будет намного сложнее.

Комментарии - один из способов сделать это:

# this is a comment

num = 1 #this is another comment

Другой способ - использоватьстроки документации.

Полезность строк документации заключается в том, что они следуют соглашениям и, как таковые, могут обрабатываться автоматически.

Вот как вы определяете строку документации для функции:

def increment(n):
    """Increment a number"""
    return n + 1

Вот как вы определяете строку документации для класса и метода:

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age
<span style="color:#66d9ef">def</span> <span style="color:#a6e22e">bark</span>(self):
    <span style="color:#e6db74">"""Let the dog bark"""</span>
    <span style="color:#66d9ef">print</span>(<span style="color:#e6db74">'WOF!'</span>)</code></pre></div>

Document a module by placing a docstring at the top of the file, for example supposing this is dog.py:

"""Dog module

This module does ... bla bla bla and provides the following classes:

- Dog
...
"""

class Dog: “”“A class representing a dog”"" def init(self, name, age): “”“Initialize a new dog”"" self.name = name self.age = age

<span style="color:#66d9ef">def</span> <span style="color:#a6e22e">bark</span>(self):
    <span style="color:#e6db74">"""Let the dog bark"""</span>
    <span style="color:#66d9ef">print</span>(<span style="color:#e6db74">'WOF!'</span>)</code></pre></div>

Docstrings can span over multiple lines:

def increment(n):
    """Increment
    a number
    """
    return n + 1

Python will process those and you can use the help() global function to get the documentation for a class/method/function/module.

For example calling help(increment) will give you this:

Help on function increment in module
__main__:

increment(n) Increment a number

There are many different standards to format docstrings, and you can choose to adhere to your favorite one.

I like Google’s standard: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

Standard allows to have tools to extract docstrings and automatically generate documentation for your code.


More python tutorials: