Как создать комментарий в python

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

Комментарии — это пояснения к исходному тексту программы. Это может быть описание работы какого-то класса, функции или, например, значение переменной.

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

Комментарии — это еще один способ сделать ваш код более читабельным. Они могут помочь не только другим людям читать и понимать ваш код, но и вам самим. Бывают ситуации, когда вы быстро пишете какой-то код, не комментируя ни строчки.

Разработчики часто забывают, как работает их собственный код. Особенно если он был написан давно.

Комментарии — это отличный способ быстро вспомнить свой код, написанный ранее.

Хороший комментарии должны быть:

• Уместными — не стоит указывать в комментариях очевидные вещи. К примеру, если вы назвали функцию print_black_list() , не нужно писать к ней комментарий # печать черного списка.
• Содержательными — должны четко описывать проблему, не должно возникнуть никаких запинок по поводу их понимания.
• Короткими — не нужно писать сочинение в комментариях.
• Актуальными — одна из проблем комментариев это их сопровождение. Код меняется, а обновлять комментарии часто забывают. Чем старше ваш комментарий, тем больше вероятность, что он лжет.

Плохой комментарий описывает код, отвечая на вопрос «что делает код?». Хороший комментарий отвечает на вопрос «зачем этот код?».

О том, как правильно писать комментарии, отлично написано в книге Роберта Мартина » Чистый код «, в главе 4 «Комментарии».

PEP 8 рекомендует использовать максимум 72 символа для комментариев на одной строке. Если ваш комментарий выходит за рамки 72 символов, его рекомендуется разделить на несколько строк.

О том, как создавать однострочные и многострочные комментарии в Python, разберем ниже.

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

Чтобы написать однострочный комментарий в Python, достаточно поставить » # » перед комментарием:

# Это однострочный комментарий print(«python») # Это тоже однострочный комментарий

Python будет считать комментарием все, что находится после «#» и до конца строки.

Многострочные комментарии

Во многих языках программирования (например С++, Go, Java, JavaScript) можно создавать многострочные комментарии конструкцией вида /* */ В Python нет возможности создавать многострочные комментарии, и такая конструкция не сработает. Однако есть альтернативные решения.

Вариант #1 — писать однострочные комментарии друг за другом:

def multiline_comment_example(): # Это многострочный комментарий, оформленный # в виде однострочных комментариев, следующих # друг за другом

Вариант #2 — заключить комментарий в тройные кавычки:

«»» Это многострочный комментарий, созданный с помощью тройных кавычек «»»

Второй вариант более удобен, но есть несколько нюансов, о которых нужно помнить.

1. На самом деле это строка, которая не назначена какой-либо переменной. Эта строка не вызывается и ни на что не ссылается, поэтому может быть использована как многострочный комментарий.
2. Если разместить такой комментарий сразу после определения функции или метода, Python будет считать его фрагментом документации, связанного с данной функцией/методом.

Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.

Источник

№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, потому что они упрощают процесс взаимодействия и ускоряют процесс рефакторинга.
 
Источник
 
Инструкции, отступы и комментарии в Python
 
Инструкции, которые может выполнять интерпретатор Python, называются операторами. Например, a = 1 — это оператор присваивания. Оператор if , оператор for , оператор while и т. д. — это другие типы операторов, которые мы обсудим позже.
 
Многострочные инструкции
 
В Python для окончания инструкции используют символ новой строки. Но можно разбить инструкцию на несколько строк символом продолжения строки (\). Например:
 
a = 1 + 2 + 3 + \ 4 + 5 + 6 + \ 7 + 8 + 9
 
Это явное продолжение строки. В Python продолжение строки выполняется внутри круглых ( ) , квадратных [ ] и фигурных скобок < >. Например, так мы можем реализовать показанную выше многострочность:
 
a = (1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9)
 
Здесь круглые скобки ( ) неявно продолжают строку. То же самое с [ ] и < >. Например:
 
colors = ['красный', 'голубой', 'зеленый']
 
Мы также можем поместить несколько выражений в одну строку с помощью точки с запятой, как показано ниже:
 
Отступы
 
Большинство языков программирования, таких как C, C ++ и Java, используют фигурные скобки < >для определения блока кода. Однако Python использует отступы.
 
Блок кода (тело функции, цикла и т. д.) начинается с отступа и заканчивается первой строкой без отступа. Размер отступа зависит от вас, но он должен быть одинаковым на протяжении всего блока.
 
Как правило, для отступов используют четыре пробела или табуляцию. Вот пример:
 
for i in range(1,11): print(i) if i == 5: break
 
Применение отступов в Python делает код аккуратным и чистым. Программы благодаря отступам выглядят последовательными. С ними блоки кода визуально легче отличать друг от друга.
 
Сравните:
 
Оба варианта допустимы и сделают одно и то же, но первый вариант — читабельнее.
 
Неправильный отступ приведет к ошибке IndentationError .
 
Комментарии
 
Комментарии очень важны при написании программы. Они описывают, что происходит внутри программы, чтобы человеку, который читает код, было проще разобраться в нем.
 
Вы можете забыть детали программы, написанной даже месяц назад. Поэтому всегда полезно уделять время на пояснение основных моментов в комментариях.
 
В Python для комментариев используется символ решетки (#).
 
Комментарий заканчивается символом новой строки. Интерпретатор Python игнорирует комментарии.
 
#Это комментарий #выводим «Привет» print('Привет')
 
Многострочные комментарии
 
В Python можно использовать многострочные комментарии. Один из способов — использовать символ решетки (#) в начале каждой строки. Например:
 
#Это длинный комментарий, #и он продолжается #на несколько строк
 
Можно поступить иначе — использовать тройные кавычки: ''' или """ .
 
Тройные кавычки обычно используются для многострочных строк. Но их также можно использовать для многострочных комментариев. Если они не являются строками документации, они не создают никакого дополнительного кода.
 
"""Это тоже пример прекрасного многострочного комментария"""
 
Строки документации (docstrings) в Python
 
Docstring — это сокращение от documentation string (строка документации).
 
Строки документации в Python — это строковые литералы, которые появляются сразу после определения функции, метода, класса или модуля.
 
При написании строк документации используются тройные кавычки. Например:
 
def double(num): """Функция, которая удваивает значение""" return 2*num
 
Строки документации появляются сразу после определения функции, класса или модуля. Это и отличает их от многострочных комментариев, написанных с использованием тройных кавычек.
 
Строка документации связана с объектом как его атрибут __doc__ .
 
Так что мы можем получить доступ к строкам документации функции с помощью следующих строк кода:
 
def double(num): """Функция, которая удваивает значение""" return 2*num print(double.__doc__)
 
Функция, которая удваивает значение
 
Источник