Оператор комментария в питоне

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

Источник

№28 Как писать комментарии / для начинающих

Добавление комментариев считается хорошей практикой. Это неисполняемые, но все равно важные части кода. Они не только помогают программистам, работающим над одним и тем же проектом, но также тестировщикам, которые могут обращаться к ним для ясности при тестировании белого ящика.

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

Комментарии — это способ выражения того, что делает программа на самом высоком уровне. Это отмеченные строчки, которые комментируют код. В Python они бывают двух типов: одно- и многострочные.

Однострочные комментарии в Python

Такой тип комментариев нужен для написания простых, быстрых комментариев во время отладки. Такие комментарии начинаются с символа решетки # и автоматически заканчиваются символом окончания строки (EOL).

 
# Хороший код документируется print("Изучите Python шаг за шагом!") 
 
При добавлении комментария важно убедиться, что у него тот же уровень отступа, что и у кода под ним. Например, нужно оставить комментарий к строке объявления функции, у которой нет отступа. Однако они имеются у блоков кода внутри нее. Поэтому учитывайте выравнивание при комментировании внутренних блоков кода.
 
 
# Создадим список месяцев 
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 
'Jul','Aug','Sep','Oct','Nov','Dec'] 
 
# Функция вывода календарных месяцев 
def showCalender(months): 
# Цикл for проходит по списку и вводит название каждого месяца 
for month in months: 
print(month) 
 
showCalender(months) 
 
Многострочные комментарии в Python
 
Python позволяет писать комментарии на нескольких строках. Они называются многострочными или блочными. Такой тип комментирования подходит для описания чего-то более сложного.
 
Этот тип комментариев нужен для описания всего последующего кода. Дальше примеры многострочных комментариев в Python.
 
С помощью символа #
 
Для добавления многострочного комментария нужно начинать каждую строку с символа решетки и одного пробела. Такой комментарий можно разбить на абзацы. Для этого достаточно добавлять пустые строки с символом перед каждым из них.
 
Примечание: в оригинале этот символ (#) называется octothorpe, что переводится с латинского как «восемь концов». Термин придумала группа инженеров в Bell Labs, которая работала над проектом первой сенсорной клавиатуры.
 
 
# Чтобы выучить любой язык, вы должны следовать этим правилам. 
# 1. Знать синтаксис, типы данных, структуры и условные операторы. 
# 2. Изучить обработку ошибок и ввод/вывод. 
# 3. Читайте о продвинутых структурах данных. 
# 4. Пишите функции и следуйте концепциям ООП. 
 
def main(): 
print("Начнем изучать Python.") 
 
Docstring в Python 
 
В Python есть такая особенность, как задокументированные строки (docstring). С их помощью программисты могут быстро добавлять комментарии для каждого модуля, функции, метода или класса в Python.
 
Задать docstring можно с помощью строковой константы. Она обязана быть первой инструкцией в определении объекта.
 
У docstring более широкая область применения, чем у комментария. Она должна описывать, что делает функция, а не как. Хорошей практикой считается добавление таких строк в каждую функцию программы.
 
Как задать docstring в Python?
 
Задать docstring в Python можно с помощью тройных кавычек Нужно добавить один набор в начале и еще один – в конце. Docstring также могут занимать по несколько строк.
 
Примечание: строки с тремя кавычками также являются docstring в Python, пусть они и могут казаться обычными комментариями.
 
В чем отличие между комментарием и docstring?
 
Строки, начинающиеся с тройной кавычки, — это все еще обычные строки, которые могут быть написаны в несколько строк. Это значит, что они все еще являются исполняемыми инструкциями. Если же у них нет метки, значит сборщик мусора уничтожит их после исполнения.
 
Интерпретатор Python не будет игнорировать их так же, как комментарии. Но если такая строка расположена сразу же после объявления функции или класса в верхней части модуля, то она станет docstring. Получить к ним доступ можно следующим образом — myobj.__doc__ .
 
 
def theFunction(): 
''' 
Эта функция демонстрирует использование docstring в Python. 
''' 
print("docstring python не являются комментариями.") 
 
print("\nВыведем docstring функции. ") 
print(theFunction.__doc__) 
 
Выводы
 
Комментарии и docstring добавляют ценности программе. Они делают программы более читаемыми и пригодными для последующей поддержки. Даже при рефакторинге сделать это будет намного проще с комментариями.
 
Разработка программного обеспечения — это лишь на 10% написание кода. Остальные 90% — поддержка.
 
Поэтому всегда добавляйте осмысленные комментарии и docstring, потому что они упрощают процесс взаимодействия и ускоряют процесс рефакторинга.
 
Источник