Комментарии и docstring: как документировать код

Пояснения в коде помогают людям понять программу. В Python для этого есть комментарии и docstring.

Комментарии через #

Комментарий начинается со знака # и игнорируется компьютером — он нужен человеку. Хороший комментарий объясняет замысел, а не пересказывает очевидное.

# считаем собранный урожай
count = count + 1

Docstring — описание функции

Docstring — это строка в тройных кавычках сразу после def. Она описывает, что делает функция, и её можно получить программно через help(). Так документируют функции, классы и модули.

def farm(n):
    """Собрать урожай с n клеток."""
    ...

Зачем это нужно

Через месяц вы не вспомните, зачем написали ту или иную строку, — а комментарий подскажет. В команде документация экономит часы. Но не переусердствуйте: понятные имена переменных часто заменяют половину комментариев.

Частые вопросы

Чем docstring отличается от комментария? Docstring — часть объекта (доступна через help), комментарий после # виден только в коде.

Замедляют ли комментарии программу? Нет, при запуске они игнорируются.