Вопрос 4 как пишутся комментарии в 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 будет считать его фрагментом документации, связанного с данной функцией/методом.

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

Шорткаты для комментариев

Процесс комментирования строк можно ускорить, используя шорткаты.

Несколько курсоров

Сразу несколько комментариев можно написать выбрав сразу несколько строк. Для разных редакторов они разные: Ctrl + Left mouse click или Alt + Left mouse click (Cmd + Left mouse click для Mac OS).

Свернуть комментарий

В некоторых редакторах (например PyCharm) можно свернуть комментарий, если он стал занимать слишком много места на экране.

Быстрое комментирование строк кода

Часто бывают ситуации, когда нужно закомментировать фрагмент кода (1 строку или сразу несколько строк подряд). Для этого просто выберите нужный фрагмент кода и нажмите Ctrl + / (Cmd + / для Mac OS)

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

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

Содержание статьи

• Комментарии в коде
• Как закомментировать и раскомментировать строки кода
• Многострочные комментарии
• Для чего используется docstring?
• PEP 8 — руководство по написанию кода на Python
• Полезные инструменты для документирования вашего кода
• Подведем итоги
• Вопросы для проверки

Делая свой код самодокументирующимся (то есть используя информативные имена) и добавляя комментарии, вы сделаете программу более читабельной для себя и для всех остальных, кто может её использовать. Это также облегчит обновление и рефакторинг кода!

В данной статье вы познакомитесь со следующими темами:

• Комментарии;
• Строки документации — Docstrings;
• PEP8 — Руководство по написанию кода;
• Другие полезные инструменты для документирования вашего кода.

Давайте начнем с комментариев.

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

Тем не менее, комментарии все равно рекомендуется использовать. Они особенно полезны для сложного кода, который нелегко понять с первого взгляда. В зависимости от компании, в которой вы работаете, вы также можете использовать комментарии для документирования багов. Например, если вы исправили ошибку, вы можете добавить комментарий, который объясняет, в чем именно она заключается.

В Python комментарии создаются с помощью знака #, за которым следует какой-либо описательный текст.

Далее представлен пример комментария в Python:

В приведенном выше коде показано, как создать простой комментарий. При выполнении кода, Python увидит символ # и проигнорирует весь следующий за ним текст. По сути, Python пропустит эту строку и попытается выполнить вторую.

Этот комментарий помечен как «плохой комментарий». Хотя он хорош для демонстрационных целей, но он не описывает код, который следует далее. По этой причине он не является полезным. Хорошие комментарии должны объяснять и описывать последующий код, его цели или что-то еще. Комментарии — это своеобразная документация вашего кода. Если они не предоставляют никакой полезной информации, то их следует удалить.

Вы также можете создавать комментарии на строке с кодом:

Здесь вы снова присваиваете переменной x значение 10, но затем добавляете символ #, который позволяет добавить комментарий к коду. Это полезно в тех случаях, когда необходимо объяснить конкретную строку кода. Если вы назвали свою переменную каким-то логическим и интуитивно понятным именем, то, скорее всего, комментарий вообще не понадобится.

В будущем вы довольно часто будете сталкиваться с таким понятием, как «закомментированный код«. Это практика добавления символа # в начале вашего кода. Таким образом, можно на всякий случай убрать какой-то кусок кода, сделав его на данный момент нерабочим.

К примеру, у вас может быть следующая строка кода:

Если вы хотите закомментировать её, это можно сделать следующим образом:

Вы можете закомментировать код в тех случаях, когда пробуете различные решения, но не хотите удалять предыдущие варианты программы. Python будет игнорировать закомментированный код, позволяя вам попробовать разнообразные пути решения задачи. Большинство редакторов кода IDE (и текстовых редакторов) предоставляют возможность выделять несколько строк и закомментировать весь блок кода.

Горячие клавиши для комментирования куса кода: (выделить нужный участок кода) +  Ctrl + /

Некоторые языки программирования, к примеру С++, предоставляют возможность создания многострочных комментариев. Для создания многострочных комментариях вы спокойно можете использовать тройные кавычки.

Далее представлен пример многострочного комментария на Python:

При использовании строк с тройным кавычками вы можете создать docstring (строки документации). По сути, мы уже это сделали когда добавили многострочный комментарии для функции test().

Давайте выясним, что это такое, и как оно используется!

Для чего используется docstring?

В Python существует концепция PEP, или Python Enhancement Proposal. PEP представляют собой предложения или новые возможности для языка Python, которые обсуждаются и согласовываются руководящим советом Python.

PEP 257 описывает соглашения о docstring. Вы можете прочитать его, если вам нужна более подробная информация. Если обобщить, то docstring — это строковый литерал, который должен быть сразу после определения названия для модуля, функции, класса или метода.

docstring создается с помощью трех двойных кавычек.

Рассмотрим пример:

В Python docstring игнорируются. Они не могут быть выполнены. Однако, когда вы добавляете docstring к модулю, функции и так далее, то данная строка становится специальным атрибутом, к которому можно получить доступ через __doc__.

Результат:

docstring можно использовать как для однострочных, так и для многострочных строк.

Далее дан пример однострочной строки:

Однострочная docstring является простой строкой текста.

Далее представлена строка docstring, используемый в функции:

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

На заметку: Хотя три двойные кавычки являются рекомендуемым стандартом, три одинарные кавычки, одни двойные кавычки и одни одинарные кавычки также работают (но одни двойные и одинарные кавычки могут содержать только одну строку, а не несколько).

Теперь давайте узнаем о создании программы в соответствии с руководством по написанию кода на Python.

PEP 8 — руководство по написанию кода на Python

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

Руководство по написанию кода Python было создано еще в 2001 году и получило название PEP8. В нем указаны соглашения по программированию на языке Python. За прошедшие годы текст несколько раз обновлялся.

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

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

Полезные инструменты для документирования вашего кода

Существует множество инструментов, которые можно использовать для написания отличного кода. Вот всего несколько из них:

• pycodestyle — Проверяет, если ваш код соответствует стандарту PEP8;
• Pylint — Инструмент для углубленного статического тестирования кода, который находит общие проблемы в коде;
• PyFlakes — Еще один инструмент для статического тестирования кода;
• flake8 — Обертка для PyFlakes, pycodestyle и McCabe;
• Black — Форматировщик кода, который в основном следует стандарту PEP8.

Вы можете использовать эти инструменты, чтобы найти проблемные места в вашем коде. Pylint, PyFlakes и flake8 кажутся мне наиболее полезными. Black пригодится, если вы работаете в команде и хотите, чтобы код каждого сотрудника был написан в одном формате. Можете добавить Black в свой список инструментов форматирования кода.

Более продвинутые IDE для Python делают определенные проверки в режиме реального времени. Например, PyCharm автоматически проверяет многие проблемы, которые фиксируют эти инструменты. WingIDE и VS Code также обеспечивают некоторую проверку кода. Можете просто попробовать различные IDE и посмотреть, что подойдет вам лучше всего.

Подведем итоги

В Python есть несколько различных способов документирования кода. Вы можете использовать комментарии, чтобы объяснить одну или несколько строк кода. Их следует использовать умеренно и по мере необходимости. Вы также можете использовать docstring, чтобы документировать модули, функции, методы и классы.

Вам также следует ознакомиться с руководством по программированию на Python, которое можно найти в PEP8. Это поможет разобраться в принципах хорошего программирования на Python. Существует несколько других руководств по стилю написания кода на Python. Например, руководство по стилю от Google или руководство по стилю Python от NumPy. Иногда ознакомление с различными руководствами может помочь развить свой собственный хороший стиль программирования.

Мы также познакомились с несколькими инструментами, которые можно использовать для улучшения вашего кода. Если у вас есть время, я советую вам ознакомиться с PyFlakes или Flake8, так как они могут помочь найти общие проблемы в вашем коде.

Комментарии являются неотъемлемой частью любой программы. Каждый язык программирования позволяет добавлять комментарии. Система комментирования Python очень проста.

• Комментарии Python начинаются с символа # и продолжаются до конца строки.
• Мы можем начать комментарий с начала строки после некоторых пробелов или кода.
• Если символ решетки присутствует в строковом литерале, он является частью строки.

Примеры

• Комментарий для переменных

name = "Pankaj"  # employee name
id = 100  # employee id

data = "#123"  # this is comment, data contains # and that is not part of the comment.

• Комментарии к функциям

# This function adds the two numbers
def add(x, y):
    return x+y

• для класса

# This class provides utility functions to work with Strings
class StringUtils:

    def reverse(s):
        return ''.join(reversed(s))

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

Иногда невозможно разместить комментарий в одной строке. В этом случае вы можете разбить на несколько строк. Для написания многострочного комментария необходимо ставить перед каждой строкой решётку (#).

# This class provides utility functions to work with Strings
# 1. reverse(s): returns the reverse of the input string
# 2. print(s): prints the string representation of the input object
class StringUtils:

    def reverse(s):
        return ''.join(reversed(s))
    
    def print(s):
        print(s)

Использование строки документации

Строки документации Python (Docstring) используются для предоставления документации для функций, классов и модулей. Они заключены в пару тройных двойных кавычек («»»). Они должны быть определены сразу после объявления функции или класса.

Давайте кратко рассмотрим несколько примеров строк документации Python.

def foo():
    """The foo() function needs to be implemented.
    Currently, this function does nothing."""
    pass


class Data:
    """ This class is used to hold Data objects information."""

Мы можем получить доступ к строке документации объекта, используя атрибут __doc__ .

print(foo.__doc__)
print(Data.__doc__)

Можно ли использовать строку документации для указания длинных многострочных комментариев?

Целью строк документации Python является предоставление документации. Иногда вы заметите, что это неправильно для длинных комментариев. Однако это не рекомендуемый подход. Если вы хотите, чтобы комментарий разбился на несколько строк, просто добавьте к каждой строке символ решетки.

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

Мы также можем использовать многострочную строку в качестве многострочного комментария. Они не генерируют код.

'''
This function read employees data from the database
emp_id: employee id, should be int
returns employee object.
'''
def read_emp_from_db(emp_id):
    i = int(emp_id)
    '''code to read emp data
    using the employee unique id number'''
    pass

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

Советы

• Всегда предоставляйте содержательные комментарии, чтобы указать использование объекта.
• Длинный комментарий лучше разбить на несколько строк.
• Не грубите в комментариях.
• Должны быть по существу. Никто не хочет читать роман в комментариях к коду.
• Избегайте бесполезных комментариев, не содержащих полезной информации. Ниже приведены несколько примеров бесполезных.

# count variable
count = 10

# foo() function
def foo():
    pass

• Иногда в комментариях нет необходимости. Достаточно иметь собственное имя самой сущности. Давайте посмотрим на пример этого сценария.

# This function add two numbers
def foo(x, y):
    return x + y


# Better to have function defined as below. There is no use of comments.

def add_two_numbers(x, y):
    return x + y

• Всегда полезно иметь систему комментариев. При работе с большим количеством членов команды и несколькими проектами в организации рекомендуется использовать политику. Например, вы можете определить такую политику:

# {Object Type} - {Usage}
# Data Object - stores the Data fetched from the database
data_obj = Data()


# {Function Short Description}
# {Input Arguments and their types}
# {Return object details}
# {Exception Details}

# This function adds all the elements in the sequence or iterable
# numbers: sequence or iterable, all the elements must be numbers
# Returns the sum of all the numbers in the sequence or iterable
# Throws ArithmeticError if any of the element is not a number


def add_numbers(numbers):
    sum_numbers = 0
    for num in numbers:
        sum_numbers += num
    return sum_numbers

Вывод

• Система комментариев Python проста и всегда начинается с символа #.
• Строка документации предназначена для документации. Не используйте его для многострочных комментариев.
• Для многострочных комментариев начинайте каждую строку с символа решетки.
• Следуйте рекомендациям по добавлению комментов в программу.
• Наличие политики — всегда хорошая идея при работе с большим количеством членов команды.

Введение в тему

Язык программирования – это что-то среднее между человеческим языком (естественным) и языком машин (бинарным). Именно поэтому нам, людям, понимать код не так просто, как привычную речь. Из-за этого иногда так сложно разобраться в программах, написанных другими людьми или самим собой, но когда-то давно. Для того, чтоб облегчить понимание кода, во многих языках программирования введён такой инструмент, как комментарии. В том числе, можно писать комментарии в Python.

Комментарии – это неисполняемые части кода на естественном языке (чаще всего на английском, но могут быть и на русском). Для их использования определён специальный синтаксис, который мы разберём в этом уроке. Комментарий python может быть однострочным и многострочным.

Использовать комментарии python считается хорошим подходом к программированию. Они помогают проводить код-ревью, реверс инжиниринг, рефакторинг, создавать документацию. Используются не только программистами, но и тестировщиками.

Писать комментарии лучше в процессе кодирования, а не после: Вы можете забыть какую-то подробность, либо отложить это в «далёкий ящик» и увеличить тем самым технический долг.

Писать в комментариях лучше всего не о том, как работает данный участок кода, а о том почему выбран именно данный подход (алгоритм, технология, и т. д.).

Если проект маленький – это вовсе не означает, что не надо его комментировать. Так как понять свой же код, спустя долгое время, бывает совсем не просто, пожалейте себя же будущего. Запомните: любой программист тратит гораздо больше времени на чтение кода, чем на само кодирование!

Комментирование — это важная часть работы программиста и правило хорошего тона. В этом уроке Вы узнаете о различных Python comments и о так называемых строках документации.

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

Для написания комментариев в Питоне используется символа хеша #. Комментарий начинается с этого символа и продолжается до конца строки.

Пример комментария из «боевого» кода, модуль ctypes стандартной библиотеки:

…
class c_void_p(_SimpleCData):
_type_ = "P"
c_voidp = c_void_p # backwards compatibility (to a bug)
_check_size(c_void_p)

…


  

Однако, если хеш-символ является часть строкового значения, интерпретатор Пайтона не станет считать комментарием то, что идёт после него.

>>>'qwerty' # комментарий

'qwerty'

>>>'qwerty # комментарий'

'qwerty # комментарий'


  

В первой строке мы записали строковое значение, обрамлённое одинарными кавычками, затем хеш и текст комментария. Во второй строке Пайтон выводит строковое значение, а комментарий игнорирует. В третьей строке мы заключаем строковое значение, хеш и текст комментария в кавычки. Как видно из четвёртой строки, интерпретатор теперь расценивает как строковое значение и то, что идёт после хеша.

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

# комментарий в отдельной строке
pass # комментарий в строке с кодом


  

В Пайтоне чаще всего применяют комментарии в отдельной строке. Это связанно с тем, что PEP8 (руководство по стилю для кода Python 3) рекомендует использовать строки длинной менее 80 символов. PyCharm (самая популярная среда разработки) рекомендует до 140 символов. Такие ограничения введены для улучшения читаемости кода. Так вот, если писать комментарий в той же строке, что и код, то он скорее всего превысит рекомендуемую ширину строки.

Итого:

— Если строка с кодом короткая и комментарий короткий – пишем их в одной строке.

— Если строка с кодом и комментарием длиннее удобочитаемой ширины, переносим комментарий на новую строку.

— Если комментарий длиннее удобочитаемой ширины, разбиваем его на несколько строк.

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

В Python, как и во многих других языках программирования, часто используются многострочные комментарии. Кроме пояснений к коду в них может указываться:

— информация о проекте

— назначении файла

— лицензии на программное обеспечение

— авторство

— версия

— контактная информация

— год публикации

— какие-то общие рассуждения, которые автор посчитал важными

— и т. д.

Стандартным способом создать многострочный комментарий является представление такого комментария как несколько однострочных, каждый на новой строке. В начале каждой строки ставится символ решетки:

# На этой строке начинается

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

# и продолжатся на следующей.

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

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

В этом варианте многострочный комментарий обрамляется тремя двойными кавычками, а хеш-символы не используются:

"""

На этой строке начинается

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

и продолжатся на следующей.

"""

  

Docstring в python

Отрывок листинга модуля concurrent стандартной библиотеки Python:

...
"""Implements ProcessPoolExecutor.

The following diagram and text describe the data-flow through the system:

|======================= In-process =====================|== Out-of-process ==|

+----------+     +----------+       +--------+     +-----------+    +---------+
|          |  => | Work Ids |       |        |     | Call Q    |    | Process |
|          |     +----------+       |        |     +-----------+    |  Pool   |
|          |     | ...      |       |        |     | ...       |    +---------+
|          |     | 6        |    => |        |  => | 5, call() | => |         |
|          |     | 7        |       |        |     | ...       |    |         |
| Process  |     | ...      |       | Local  |     +-----------+    | Process |
|  Pool    |     +----------+       | Worker |                      |  #1..n  |
| Executor |                        | Thread |                      |         |
|          |     +----------- +     |        |     +-----------+    |         |
|          | <=> | Work Items | <=> |        | <=  | Result Q  | <= |         |
|          |     +------------+     |        |     +-----------+    |         |
|          |     | 6: call()  |     |        |     | ...       |    |         |
|          |     |    future  |     |        |     | 4, result |    |         |
|          |     | ...        |     |        |     | 3, except |    |         |
+----------+     +------------+     +--------+     +-----------+    +---------+

Executor.submit() called:
...
  

В Python существует прекрасный способ предоставления документации для логически обособленных частей программы. Docstring должны быть определены сразу после объявления функции, метода или класса, либо в начале модуля. Этот инструмент широко применяется – стандартная библиотека тому подтверждение. Можно сказать, что модуль, не имеющий строк документации, не может считаться готовым к релизу. Согласно PEP 8 (Python Enhancement Proposal), в Python docstring необходимо использовать для каждого создаваемого блока кода в качестве поясняющей конструкции.

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

— Первая строка это лаконичное описание блока.

— Первая строка начинается с Заглавной буквы.

— Первая строка заканчивается точкой.

— Если строка документа состоит из нескольких строк, то вторая строка должна быть пустой.

— Начиная с третьей строки идёт более детальное описание блока (его сторонние эффекты, описание структуры, интерфейс и т. д.)

Есть несколько инструментов, которые генерируют документацию из строк документации в автоматическом режиме. Назовём некоторые из них: расширение autodoc для Sphinx, PyDoc, Doxygen,  pdoc.

Как задать docstring в python

Docstring необходимо помещать на следующей строке после определения класса, метода, функции или модуля, заключая текст в тройные кавычки.

def foo():
"""Функция для примера.

Эта функция ничего не делает."""
pass


  

В этом коде Вы можете видеть простейший пример строк документации. Первая строка коротко описывает функцию, вторая отделяет дальнейший текст, а, начиная с третьей строки, идёт пояснение каких-то деталей.

В чём отличие между комментарием и docstring

Комментарии полностью игнорируются интерпретатором Питона. С docstring всё иначе: они обрабатываются и помещаются в полученный байт-код. Во время выполнения программы строки документации можно вывести на экран с помощью функции help() или получить к ним доступ используя метод __doc__.

Какими должны быть комментарии

Как говорилось выше, комментарии в Python очень важны. Их использование тесно связано с понятием «чистый код». Вот несколько советов о том, какими должны и какими не должны быть комментарии:

— Комментарий должен быть содержательным.

— Описывайте не «как», а «почему». Важно объяснить свой выбор в пользу того или иного пути решения поставленной задачи.

— Описывайте неочевидные места программы, но стремитесь к тому, чтоб таких мест не было.

— Избегайте длинных комментариев. Информацию из таких комментариев лучше перенести в docstring.

— Избегайте таких комментариев, которые не содержат полезной информации.

— Используйте одинаковый стиль оформления комментариев во всём проекте.

Помните, что комментарии достаточно сложно поддерживать в актуальном состоянии. Всё в порядке, когда это маленький проект без горящих сроков. Но, представьте ситуацию, когда в проекте участвует сотня программистов. Один программист пишет строку кода и сразу же её комментирует. Затем он увольняется. Вдруг, через час после релиза, где-то в этом месте всплывает баг. Уже другой программист берётся фиксить этот баг и, в результате, полностью переписывает функцию, но, так как дедлайн, да и вообще лень, он оставляет старые комментарии – всё равно они не исполняются интерпретатором.

Представили? А теперь представьте, что Вы приходите работать в эту компанию, начинаете вникать в проект и читаете именно эти строки кода. Код об одном, комментарии о другом (о старом коде). Здесь они не только не помогают, но и сбивают с толку и лучше бы их вообще не было.

Идеальный код должен быть понятен на столько, чтобы не было необходимости в комментариях. Это достигается правильным выбором имён переменных, функций, классов и прочих сущностей. Но, это в идеальном мире. В нашем же мире совсем без комментариев не обойтись.

Комментарии в Python – важный инструмент для программистов. Комментарии обычно используются для объяснения кода. Мы можем легко понять код, если у него есть правильное объяснение. Хороший программист должен использовать комментарии, потому что в будущем кто-то захочет изменить код, а также реализовать новый модуль; тогда это можно сделать легко.

В другом языке программирования, таком как C ++, используются: // – для однострочного комментария и / * …. * / – для многострочного комментария, но Python предоставляет однострочный комментарий. Чтобы применить комментарий в коде, мы используем решётку(#) в начале оператора или кода.

Давайте разберемся в следующем примере.

 # Это оператор печати
 print("Привет, Python")

Здесь мы написали комментарий к оператору печати с помощью решетки(#). Это не повлияет на наш оператор печати.

Мы должны использовать решётку(#) в начале каждой строки кода, чтобы применить многострочный комментарий Python. Рассмотрим следующий пример.

# Первая строка комментария
 # Вторая строка комментария
 # Третья строка комментария

Пример:

# Переменная a содержит значение 5
 # Переменная b имеет значение 10
 # Переменная c содержит сумму a и b
 # Распечатать результат
 а = 5
 б = 10
 с = а + Ь
 print("Сумма:", c)

Выход:

The sum is: 15 

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

Мы также можем использовать тройные кавычки(” ” ”) для многострочного комментария. Тройные кавычки также используются для форматирования строк. Рассмотрим следующий пример.

Комментарий строки документации

Комментарий к строке документации в основном используется в модуле, функции, классе или методе. Это строка документации Python. Мы объясним класс / метод в следующих руководствах.

Пример:

def intro():  
  """ 
  This function prints Hello Joseph 
  """  
  print("Hi Joseph")              
intro() 

Hello Joseph
Мы можем проверить строку документации функции с помощью атрибута __doc__.

Обычно в качестве отступа используются четыре пробела. Размер отступа зависит от пользователя, но он должен быть одинаковым во всем блоке.

def intro():  
  """ 
  This function prints Hello Joseph 
  """  
  print("Hello Joseph")              
intro.__doc__

Выход:

Output:
'n  This function prints Hello Josephn  '

Примечание. Строка документации должна быть первой в функции; в противном случае интерпретатор Python не сможет получить строку документации.

Отступы Python

Отступы Python используются для определения блока кода. Другие языки программирования, такие как C, C ++ и Java, используют фигурные скобки {}, тогда как Python использует отступы. Пробелы используются в Python как отступ.

Отступ используется в начале кода и заканчивается непреднамеренной строкой. Тот же отступ строки определяет блок кода(тело функции, цикл и т. д.)

Обычно в качестве отступа используются четыре пробела. Размер отступа зависит от пользователя, но он должен быть одинаковым во всем блоке.

for i in range(5):  
    print(i)  
    if(i == 3):  
        break

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

Рассмотрим следующий пример.

dn = int(input("Enter the number:"))  
if(n%2 == 0):  
    print("Even Number")  
else:  
    print("Odd Number")  
     
print("Task Complete")  

Выход:

Enter the number: 10 
Even Number 
Task Complete 

Приведенный выше код, if и else – два отдельных блока кода. Оба блока кода имеют отступ в четыре пробела. Оператор print(«Задача завершена») не имеет отступа в четыре пробела и находится вне блока if-else. Если отступ используется неправильно, это приведет к ошибке IndentationError.

Comments are text notes added to the program to provide explanatory information about the source code. They are used in a programming language to document the program and remind programmers of what tricky things they just did with the code and also help the later generation for understanding and maintenance of code. The compiler considers these as non-executable statements. Since comments do not execute, when you run a program you will not see any indication of the comment in the output.

Syntax: The hash(#) symbol denotes the starting of a comment in Python.  

# This is a comment in Python

Example:

Output :  

GFG

Comments should be made at the same indent as the code it is commenting on.

Hello!!
GeeksforGeeks
Welcome to Comments in Python

Types of Comments

1. Single-Line Comments: Comments starting with a ‘#’ and whitespace are called single-line comments in Python. These comments can only stretch to a single line and are the only way for comments in Python. e.g.

# This a single line comment.

2. Multi-line (Block) comments: Unlike other programming languages Python doesn’t support multi-line comment blocks out of the box. However we can use consecutive # single-line comments to comment out multiple lines of code. Some examples of block comments-

# This type of comments can serve
# both as a single-line as well
# as multi-line (block) in Python.

3. Inline Style comments: Inline comments occur on the same line of a statement, following the code itself. Generally, inline comments look like this:

x = 3        # This is called an inline comment

a = b + c    # Adding value of 'b' and 'c' to 'a'

4. Docstring comments: Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. It’s specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, the docstring should describe what the function does, not how.

Example: 

Output: 

Using __doc__:
Demonstrates docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:

my_function()
    Demonstrates docstrings and does nothing really.

Advantages and Uses of Comments:

Planning and reviewing: In the comments, we can write the pseudocode which we planned before writing the source code. Pseudocode is a mixture of natural language and high-level programming language. This helps in reviewing the source code more easily because pseudocode is more understandable than the program. 

Example:

Output :

13

Debugging: The brute force method is a common method of debugging. In this approach, print statements are inserted throughout the program to print the intermediate values with the hope that some of the printed values will help to identify the errors. After doing debugging we comment on those print statements. Hence comment is also used for debugging.

 
Output :

True

Comments are text notes added to the program to provide explanatory information about the source code. They are used in a programming language to document the program and remind programmers of what tricky things they just did with the code and also help the later generation for understanding and maintenance of code. The compiler considers these as non-executable statements. Since comments do not execute, when you run a program you will not see any indication of the comment in the output.

Syntax: The hash(#) symbol denotes the starting of a comment in Python.  

# This is a comment in Python

Example:

Output :  

GFG

Comments should be made at the same indent as the code it is commenting on.

Hello!!
GeeksforGeeks
Welcome to Comments in Python

Types of Comments

1. Single-Line Comments: Comments starting with a ‘#’ and whitespace are called single-line comments in Python. These comments can only stretch to a single line and are the only way for comments in Python. e.g.

# This a single line comment.

2. Multi-line (Block) comments: Unlike other programming languages Python doesn’t support multi-line comment blocks out of the box. However we can use consecutive # single-line comments to comment out multiple lines of code. Some examples of block comments-

# This type of comments can serve
# both as a single-line as well
# as multi-line (block) in Python.

3. Inline Style comments: Inline comments occur on the same line of a statement, following the code itself. Generally, inline comments look like this:

x = 3        # This is called an inline comment

a = b + c    # Adding value of 'b' and 'c' to 'a'

4. Docstring comments: Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. It’s specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, the docstring should describe what the function does, not how.

Example: 

Output: 

Using __doc__:
Demonstrates docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:

my_function()
    Demonstrates docstrings and does nothing really.

Advantages and Uses of Comments:

Planning and reviewing: In the comments, we can write the pseudocode which we planned before writing the source code. Pseudocode is a mixture of natural language and high-level programming language. This helps in reviewing the source code more easily because pseudocode is more understandable than the program. 

Example:

Output :

13

Debugging: The brute force method is a common method of debugging. In this approach, print statements are inserted throughout the program to print the intermediate values with the hope that some of the printed values will help to identify the errors. After doing debugging we comment on those print statements. Hence comment is also used for debugging.

 
Output :

True