Комментарии в Python 3

Комментарии в программе — это часть кода, которая игнорируется интерпретатором или компилятором. Они нужны, чтобы:

• сделать код более читабельным;
• объяснить, что и зачем делает код;
• предотвратить выполнение части кода при его тестировании/выполнении;
• оставить заметку о том, что необходимо сделать/переделать/убрать.

В целом, комментарии нужны, чтобы сделать жизнь программиста проще — для компьютера они никакой роли не играют. Хотя в некоторых подходах к программированию, например в экстремальном программировании, считается, что если код нуждается в комментариях, то этот код плохой. 

В этой статье вы узнаете, как оставлять комментарии в Python 3, что такое Docstring и PEP. 

Комментарии в Python

В разных языках программирования у комментариев разный синтаксис. Часто это двойной слеш (//). В Python 3 комментарии в коде начинаются со знака «#». Например:

Также комментарий можно разместить прямо в строке с кодом:

Комментарии должны быть полезны для читателя. Например, такой комментарий не принесет пользы:

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

Также в виде комментария можно оформить часть кода, чтобы она не выполнялась. Это может быть полезно при тестировании и отладке кода.

Предположим, нам нужно закомментировать такой код:

Это, кстати, код из нашего туториала по созданию веб-приложения с помощью Flask. Прочитать его можно здесь. Цель комментирования — сделать этот блок кода понятным. Его можно закомментировать таким образом: 

Иногда вручную комментирование кода Python неудобно. Чтобы оформить блок кода в виде однострочных комментариев, можно использовать горячие клавиши для комментирования кода Python:

• PyCharm: Ctrl + /;
• Visual Studio Code: чтобы закомментировать/раскомментировать строку Ctrl + /, чтобы блок кода – Shift + Alt + A;
• Eclipse: чтобы закомментировать/раскомментировать строку Ctrl + /, чтобы блок кода – Ctrl + Shift + /;
• Visual Studio: Ctrl + K затем Ctrl + C, чтобы закомментировать блок кода, и Ctrl + K затем Ctrl + U, чтобы раскомментировать блок кода.

Docstring в Python

Docstring — это строковый литерал, который размещается сразу после объявления модуля, функции, класса и других структур. Это удобный способ документирования кода, к которому можно обращаться. Docstring появился в Python в 2001 году и описан в PEP 257.

Что такое PEP?

Развитие языка Python происходит по четко регламентированному процессу создания, обсуждения, отбора и реализации документов PEP (Python Enhancement Proposal). В PEP размещаются предложения по развитию языка: внедрению новых функций, изменению существующих и т.п. Одним из самых известных (и полезных) документов PEP является PEP 8 — в нем отображен свод рекомендаций и соглашений по написанию кода на Python. Если вы планируете писать на Python, то вам стоит ознакомиться с этим соглашением. Правил довольно много, и для их соблюдения существуют специальные инструменты. Некоторые полезные инструменты вы сможете найти чуть ниже.

Вернемся в Docstring. Docstring — первая инструкция в объявлении объекта. Вот пример:

Синтаксис Docstring — это три кавычки в начале и в конце. Также можно использовать вместо кавычек апострофы и не три, а два или один символ. Но PEP 257 рекомендует использовать именно три кавычки. 

К docstring объекта можно обратиться с помощью метода __doc__:

Результат: функция вычитает из числа a число b.

Также свойство __doc__ можно использовать для получения информации о встроенных методах Python, например print:

Вывод:

Строковые литералы, встречающиеся где-то в коде Python, также могут выполнять роль документации. Они не будут распознаны компилятором байт-кода Python и не будут доступны во время выполнения программы с помощью свойства __doc__ . Но есть два дополнительных типа docstring, которые могут быть извлечены из кода программными инструментами.

Additional docstring

Additional docstring — это строковые литералы, которые игнорируются компилятором Python, но при этом распознаются средствами Docutils. Они размещаются сразу после docstring. Вот пример:

Attribute docstrings

Attribute docstring — это строковые литералы, которые встречаются сразу после простого присваивания на уровне модуля, класса или метода __init__. Например:

Вот основные рекомендации из PEP 257 по использованию docstring:

• После всех docstring оставляйте пустую строку.
• Docstring скрипта должен представлять собой сообщение "о правильном использовании", который, возможно, будет выведен пользователю при вызове скрипта с неправильными аргументами. Docstring должен описывать функционал, синтаксис параметров, переменные среды и используемые файлы.
• Docstring модуля должен содержать список важных объектов и однострочное пояснение для каждого из них.
• Docstring функции или метода должен описывать поведение, аргументы, return, возможные исключения и ограничения работы.
• Docstring класса должен содержать методы, переменные экземпляра и описывать поведение класса.
• Конструктор класса должен иметь свою отдельную документационную строку для метода __init__.
• Если класс является потомком и его поведение в основном наследуется от основного класса, в его документации необходимо упомянуть об этом и описать возможные различия. 

Полезные инструменты

Вместо заключения приведем список инструментов, которые будут полезны при работе с PEP 8 и комментариями в Python 3:

• pycodestyle — проверяет соответствие вашего кода PEP 8;
• Black — форматирует код в соответствии со стандартом PEP 8 (в основном);
• Doxygen, PyDoc, pdoc — автоматически формируют документацию из docstring.

Кстати, в официальном канале Timeweb Cloud мы собрали комьюнити из специалистов, которые говорят про IT-тренды, делятся полезными инструкциями и даже приглашают к себе работать.