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

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

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

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

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

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

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

#Код выводит в консоль строку "Hello, World!"
print("Hello, World!")

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

print("Hello, World!") #Код выводит в консоль строку "Hello, World!"

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

#что-то этот код явно делает
print("Hello, World!")

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

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

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

db_lp = sqlite3.connect('login_password.db')
cursor_db = db_lp.cursor()
sql_create = '''CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);'''

cursor_db.execute(sql_create)
db_lp.commit()

cursor_db.close()
db_lp.close()

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

db_lp = sqlite3.connect('login_password.db')  #Создаем базу данных login_password
cursor_db = db_lp.cursor()  #Объект класса Cursor для выполнения SQL-запросов

#SQL-запрос для создания таблицы password в базе данных 
sql_create = '''CREATE TABLE passwords(  
login TEXT PRIMARY KEY, 
password TEXT NOT NULL);''' 

cursor_db.execute(sql_create)  #Выполняем запрос sql_create 
db_lp.commit()  #Подтверждаем изменения

#Закрываем Cursor и базу данных 
cursor_db.close()   
db_lp.close()

Иногда вручную комментирование кода 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 — первая инструкция в объявлении объекта. Вот пример:

def function (x,y,z): 
""" Docstring этой функции""" 
def inner_function (): 
""" Docstring вложенной функции """

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

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

def subtraction (a,b):     
"""Функция вычитает из числа a число b"""
    return (a-b) 
print(subtraction.__doc__)

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

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

print(print.__doc__)

Вывод:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False) 
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

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

Additional docstring

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

def function(arg):    
"""Это docstring этой функции. Он будет доступен с помощью свойства  __doc__."""
"""
Это additional docstring, он будет проигнорирован компилятором, но распознан Docutils.
"""
pass

Attribute docstrings

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

def f(x):
"""Это docstring этой функции. Он будет доступен с помощью свойства  __doc__"""
    return x**2
f.a = 1
""" Это attribute docstring для атрибута функции f.a, он будет проигнорирован компилятором, но распознан Docutils."""

Вот основные рекомендации из 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-тренды, делятся полезными инструкциями и даже приглашают к себе работать.