В коде уроков и заданий вы постоянно встречаете комментарии — подсказки или пояснения к коду. Строки комментариев не обрабатываются в Python и предназначены исключительно для разработчика.Есть и другой способ документирования кода. Загляните в любой файл Django, например. в shortcuts.py из пакета shortcuts. В начале файла и в теле функций вы увидите блоки текста, обрамлённые тройными кавычками.
"""
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 описывают весь модуль целиком. Вот как может выглядеть документированный код:
"""Документация модуля. Описывает работу классов и функций.
Размещается в верхней части файла (начиная с 1-й строки).
"""
def foo(self):
"""Описывает работу функции foo."""
...
class Test:
"""Класс Test используется для демонстрации docstring.
После этой строки нужна пустая строка, поскольку методы в классе
отделяются одной пустой строкой.
"""
def first(self):
"""Описывает метод first и демонстрирует перенос строки
документации.
"""
...
Строки документации пишутся по определённым правилам. Соблюдение этих правил упростит чтение вашей документации и, дополнительно, создаст вам хорошую репутацию в команде. Правила оформления docstring описаны в стандарте PEP257.
Основные правила оформления docstring
- После первых тройных кавычек
"""не должно быть пробела. - Докстринг начинается с заглавной буквы и заканчивается точкой.
"""Возвращает число 1."""
- Если строка документации не умещается на одну строку — можно её перенести. Отступы на новой строке должны выровнять текст по кавычкам.
def foo():
"""Можно перенести
так.
"""
def bar():
"""
А можно -
так.
""" - Если документируется класс — после строки документации оставляется пустая строка. В остальных случаях код должен начинаться сразу после докстринга.
Существуют разные стили оформления строк документации. Вот самые популярные:
В учебных проектах Яндекс.Практикума строгое соблюдение стиля необязательно, достаточно коротко на русском (или английском) языке описать принцип работы документируемого кода.
Как можно вызвать docstring
По сравнению с обычными комментариями docstring обладает серьёзным преимуществом: к нему можно обратиться программно. Например, можно вызвать в консоль docstring импортируемой функции, не открывая файл, в котором эта функция хранится. С обычными комментариями такой номер не пройдёт.Самый простой способ получить docstring из какого-то объекта — использовать атрибут doc. 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() тоже есть докстринг, и в нём может оказаться что-нибудь интересное.Вызвать документацию можно из любого объекта, важно лишь правильно указать этот объект. Скопируйте и запустите код, посмотрите, как он выведет документацию для разных объектов:
"""Документация модуля. Описывает работу классов и функций.
Размещается в верхней части файла (начиная с первой строки).
"""
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.
"""Документация модуля. Описывает работу классов и функций.
Размещается в верхней части файла (начиная с первой строки).
"""
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 помогает в чтении. Докстринг — это и признак уважения и реальная помощь коллегам, работающим с вашим кодом; это признак хорошего тона и профессионализма.