Docstring: документируй это!

В коде уроков и заданий вы постоянно встречаете комментарии — подсказки или пояснения к коду. Строки комментариев не обрабатываются в Python и предназначены исключительно для разработчика.

Есть и другой способ документирования кода. Загляните в любой файл Django, например. в shortcuts.py из пакета shortcuts. В начале файла и в теле функций вы увидите блоки текста, обрамлённые тройными кавычками.

Скопировать кодPYTHON
"""
This module collects helper functions and classes that "span" multiple levels
of MVC. In other words, these functions/classes introduce controlled coupling
for convenience's sake.
"""
...

def render(...):
    """
    Return a HttpResponse whose content is filled with the result of calling
    django.template.loader.render_to_string() with the passed arguments.
    """
    ...

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

Что и как можно документировать

Принято писать документацию для публичных функций, методов и классов. Иногда в docstring описывают весь модуль целиком.

Вот как может выглядеть документированный код:

Скопировать кодPYTHON
"""Документация модуля. Описывает работу классов и функций. 
Размещается в верхней части файла (начиная с 1-й строки).
"""


def foo(self):
    """Описывает работу функции foo."""
    ...


class Test:
    """Класс Test используется для демонстрации docstring. 
    После этой строки нужна пустая строка, поскольку методы в классе 
    отделяются одной пустой строкой.
    """
        
    def first(self):
        """Описывает метод first и демонстрирует перенос строки 
        документации.
        """
        ...

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

Основные правила оформления docstring

После первых тройных кавычек """ не должно быть пробела.
Докстринг начинается с заглавной буквы и заканчивается точкой.

Скопировать кодPYTHON
"""Возвращает число 1."""

Если строка документации не умещается на одну строку — можно её перенести. Отступы на новой строке должны выровнять текст по кавычкам.

Скопировать кодPYTHON
def foo():
    """Можно перенести
    так.
    """


def bar():
    """
    А можно - 
    так.
    """

Если документируется класс — после строки документации оставляется пустая строка. В остальных случаях код должен начинаться сразу после докстринга.

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

В учебных проектах Яндекс.Практикума строгое соблюдение стиля необязательно, достаточно коротко на русском (или английском) языке описать принцип работы документируемого кода.

Как можно вызвать docstring

По сравнению с обычными комментариями docstring обладает серьёзным преимуществом: к нему можно обратиться программно. Например, можно вызвать в консоль docstring импортируемой функции, не открывая файл, в котором эта функция хранится. С обычными комментариями такой номер не пройдёт.

Самый простой способ получить docstring из какого-то объекта — использовать атрибут doc. Python автоматически создаёт этот атрибут для любого объекта.

Откройте пустой файл в редакторе и запустите этот код:

Скопировать кодPYTHON
import math

# Спросим, что хорошего в этой библиотеке
print(math.__doc__)

# Будет напечатано:
# This module provides access to the mathematical functions
# defined by the C standard.

Посмотрите docstring функции sqrt() из библиотеки math, его можно вызвать через math.sqrt.__doc__.

У встроенной функции print() тоже есть докстринг, и в нём может оказаться что-нибудь интересное.

Вызвать документацию можно из любого объекта, важно лишь правильно указать этот объект. Скопируйте и запустите код, посмотрите, как он выведет документацию для разных объектов:

Скопировать кодPYTHON
"""Документация модуля. Описывает работу классов и функций. 
Размещается в верхней части файла (начиная с первой строки).
"""
def tricky_func(self):
    """Описывает работу функции tricky_func."""
    ...


class Test:
    """Класс Test используется для демонстрации docstring."""

    def first(self):
        """Описывает метод first и демонстрирует перенос строки 
        документации.
        """
        ...


print(__doc__)
print(tricky_func.__doc__)
print(Test.__doc__)
print(Test.first.__doc__)

Чтобы избавиться от пробелов при печати многострочных докстрингов, можно применить метод cleandoc() из модуля inspect.

Скопировать кодPYTHON
"""Документация модуля. Описывает работу классов и функций. 
Размещается в верхней части файла (начиная с первой строки).
"""
import inspect


def tricky_func(self):
    """Описывает работу функции tricky_func."""
    ...


class Test:
    """Класс Test используется для демонстрации docstring."""

    def first(self):
        """Описывает метод first и демонстрирует перенос строки 
        документации.
        """
        ...


print("Без применения cleandoc:")
print(Test.first.__doc__)
print("С применением cleandoc:")
print(inspect.cleandoc(Test.first.__doc__))

Стиль леди и джентльменов

Документировать код необязательно, программа будет работать и без этого. Однако docstring применяют во всех крупных проектах.

Код читают намного чаще, чем пишут, и docstring помогает в чтении.

Докстринг — это и признак уважения и реальная помощь коллегам, работающим с вашим кодом; это признак хорошего тона и профессионализма.

Софт - задание

Вызовите докстринг из какой-нибудь встроенной функции и опубликуйте его в чате тимворка: пусть ваши однокурсники попробуют определить, что это за функция.

Задача

Программа работает, но в ней полным-полно ошибок в стиле оформления. Приведите её в порядок.

Подсказка

Взламывайте систему! Ваша задача — самостоятельно выполнить задание, и самым простым решением будет скопировать код в редактор, проверить его линтером и исправить в соответствии с подсказками.

message — строка перенесена с помощью бэкслеша, так нельзя;
from math import * — импортирование всего содержимого модуля может привести к проблемам; лучше импортировать from math import sqrt
import itertools — пакет импортирован, но не применяется;
во многих местах кода отсутствуют необходимые пробелы или стоят лишние;
между блоками кода неправильное количество пустых строк;
название функции написано в стиле CamelCase и не соответствует PEP8;
имя переменной Number не соответствует PEP8;
"Мы вычислили корень квадратный ..." — неконсистентные кавычки, в остальном коде применяются одинарные;
print(f"Мы вычислили корень квадратный из введённого вами числа. Это будет:... — слишком длинная строка, надо переносить;
""" Вычисляет квадратный корень""" — докстринг оформлен не по PEP257;
в f-строках не должно быть исполняемой логики. Вынесите логику в отдельную переменную;
в коде не должно быть неиспользуемых переменных.

 
from math import sqrt
​
​
message = (f'Добро пожаловать в самую лучшую программу для вычисления '
          f'квадратного корня из заданного числа')
​
​
def calculate_square_root(number):
    """Вычисляет квадратный корень."""
    return sqrt(number)
​
def calc(your_number):
    """Вычисляет квадратный корень."""
    if your_number <= 0:
        return    
    root = 0
    root = calculate_square_root(your_number)
    print(f'Мы вычислили корень квадратный из введенного вами числа.'
          f' Это будет: {root}')
​
​
print(message)
calc(25.5)
​

Затраченное время того стоило: красивый код и читать приятно. Правильно оформленный код — признак хорошего разработчика и серьёзный плюс при приёме на работу.

Docstring: документируй это!

Что и как можно документировать

Основные правила оформления docstring

Как можно вызвать docstring

Стиль леди и джентльменов

Софт - задание

1.Начало

2.Встроенные типы данных

3.Булева алгебра. Условные операторы

4.Последовательности

5.Python «под капотом»

6.Последовательности: продолжение

7.Множества set()

8.Словари

9.Типы данных

10.Создание функций

11.Стандартная библиотека

12.Финальный проект спринта: программный модуль для фитнес-трекера

13.Мотивация и не только

14.Самое необходимое об ООП

15.Знакомство с командной строкой

16.Настройка окружения: VSCode, Git, venv, pytest

17.Аннотации типов

18.Требования к коду

19.Energy Management

20.Финальный проект спринта: калькулятор денег и калорий

1.Линтеры и правила оформления кода

2.Docstring: документируй это!