Документирование в Python

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

 

Функция help

Возможно, вы уже сталкивались со встроенной функцией help. Она позволяет получить справочную информацию по объекту, если она в нем имеется.

Функцию help() можно вызвать без параметров, вот пример такого вызова в python 3.12

Здесь мы видим приветственное сообщение (в других версиях python оно может выглядеть иначе) и далее говорится, что вы можете передать в функцию help любое имя, информацию по которому вы хотите получить. Давайте получим справку по функции print

В выводе мы видим короткое описание функции, а также предназначение всех ее параметров. Вы можете попробовать вызвать help, передав в него имя переменной

В таком случае Python сообщит, что у объекта, хранящегося по имени my_str, нет справочной документации. Но советует обратиться за справкой по типу данных str. Если вызвать help(str), то вы получите большой объем справочной информации о встроенном типе str c кратким описанием всех доступных методов строк. Попробуйте сами взглянуть на вывод вызова help(str) или другого встроенного типа данных.

Работа функции help завязана на таком механизме, как строка документации. Давайте с ним познакомимся.

 

Docstring - документирование кода

Docstring( сокращение от слов «documentation string») переводится как строка документирования. Это специальный механизм, который позволяет добавлять пояснения внутри вашего кода определенным образом и в определенном месте. При помощи docstring вы можете:

  • Оставить краткое описание вашего кода,
  • Рассказать о всех параметрах, которые в нем используются
  • Пояснить зачем нужен каждый параметр и за что он отвечает.

Эта информация может пригодиться другим разработчикам, которые в будущем будут взаимодействовать с вашим кодом.

Соглашение о docstring регламентирует стандарт PEP-257, можете самостоятельно его изучить, в нем определены базовые общепринятые правила написания.

Docstring  у пользовательских функций

Когда вы определяете свою собственную функцию, то по умолчанию у нее атрибут __doc__ является пустым, другими словами он будет равен None. Давайте в этом убедимся. Возьмём к примеру функцию get_even, которая принимает список и на его основании создаёт новый список только с чётными числами. Не определяем внутри get_even строку документирования и вызовем функцию help()

def get_even(lst):
    even_lst = []
    for elem in lst:
        if elem % 2 == 0:
            even_lst.append(elem)
    return even_lst
print(get_even.__doc__)
print('-----------------------------')
help(get_even)

Видим, что в атрибуте __doc__ хранится значение None. Чтобы изменить значение атрибута __doc__ , необходимо на первой строчке после определения функции создать объект строки, где указать описание вашей функции. Вот пример:

def get_even(lst):
    'Функция возвращает список из чётных чисел списка lst'
    even_lst = []
    for elem in lst:
        if elem % 2 == 0:
            even_lst.append(elem)
    return even_lst
    
    
print(get_even.__doc__)
print('-----------------------------')
help(get_even)

Обратите особое внимание, что на первой строке должен быть именно строковый тип данных, а не комментарий. Комментарии игнорируются интерпретатором, поэтому атрибут __doc__ будет принимать значение None и в вызове функции help() ничего не будет.

Также необходимо запомнить, что к docstring будет относиться только первая строка после объявления функции (за исключением комментариев). Взгляните на этот пример

def get_even(lst):
    #comment
    'Функция возвращает '
    'список из чётных чисел списка lst'
    even_lst = []
    for elem in lst:
        if elem % 2 == 0:
            even_lst.append(elem)
    return even_lst
print(get_even.__doc__)
print('-----------------------------')
help(get_even)

В выводе видим только текст «Функция возвращает», содержащийся в первой строке после комментария. Вторая строка с текстом «список из чётных чисел списка lst» не относится в данном случае к строке документирования.

Если же в первой строке будет что-то другое, к примеру, присваивание переменной, то в docstring вообще ничего не попадёт

def get_even(lst):
    even_lst = []
    #comment
    'Функция возвращает '
    'список из чётных чисел списка lst'
    even_lst = []
    for elem in lst:
        if elem % 2 == 0:
            even_lst.append(elem)
    return even_lst
print(get_even.__doc__)
print('-----------------------------')
help(get_even)

В docstring  попадает обязательно только первая строка после определения функции.

 

Многострочные docstring  в Python 

Так как же тогда делать большие и объемные строки документации, которые состоят из нескольких строк? Все просто - используйте многострочную строку. Пример:

def get_even(lst):
    '''Функция возвращает
    список из чётных чисел
    списка lst'''
    even_lst = []
    for elem in lst:
        if elem % 2 == 0:
            even_lst.append(elem)
    return even_lst
    
    
print(get_even.__doc__)
print('-----------------------------')
help(get_even)

 

Использование docstring

Можно выделить три места использования docstring:

  1. В функциях. Данное применение мы рассмотрели в рамках этого урока.
     

  2. В модулях. Под модулем подразумевается целиком вся ваша программа, которая сохранена в виде файла с расширением .py. У модуля тоже может быть строка документации. Ниже представлен пример получения справки по встроенному модулю math

    import math
help (math)

  3. В классах. Такие объекты, как классы, мы будем изучать в рамках курса по ООП. 

Перейти к следующему шагу

Комментарии