Что такое docstring? С чем его едят?

Taras

4-й уровень

Docstring - это такая строковая переменная, которая идет сразу за объявлением модуля, функции, класса, метода. Таким образом питон предоставляет удобный способ добавления документации. Существует много средств для автоматического генерирования документации, которые используют докстринг. Докстринг очень похож на комментарий, но заклчается в тройные кавычки. Все функции должны иметь докстринг, который содержит описание работы этой функции. Комментарии же обычно пытаются объяснить эту работу. На первой строке пишем короткую фразу, такую как: "Решает уравнение ax^2+ bx + c =0". Ниже идет более подробный разбор различный случаев. Достать соответсвующий докстринг можно, обратившись к атрибуту doc объекта.

Примеры использования

Теперь давайте посмотрим на докстринг в действии.

"""
Here be a docstring
It can have multiple lines.
                 Or spaces.
"""

def function(a,b,c):
    """
    Do nothing important
    Only have documentation string
    """
    pass

class  UselessClass(object):
    """
    Docstring of class
    This class can't anything
    """
    def method_of_class(self):
        """ doctring of class's methos """

Для того чтобы увидеть результат работы мы можем выполнить несколько команд:

import test_docstring
print(test_docstring.function.__doc__)
print(test_docstring.UselessClass.method_of_class.__doc__)
help(test_docstring.UselessClass)

Как легко заметить докстринг сильно повышает удобство использования модулей. Программисту, который не писал код будет несложно понять что делает та или иная функция. Самое важное, что надо помнить при работе с docstring - Докстринг вы пишите для людей, которые будут использовать ваш код, а комментарии для тех, кто будет в нем разбираться.