№28 Как писать комментарии / для начинающих
Добавление комментариев считается хорошей практикой. Это неисполняемые, но все равно важные части кода. Они не только помогают программистам, работающим над одним и тем же проектом, но также тестировщикам, которые могут обращаться к ним для ясности при тестировании белого ящика.
Куда лучше добавлять комментарии при создании или обновлении программы, иначе можно утратить контекст. Комментарии, добавленные позже, могут быть далеко не настолько эффективными.
Комментарии — это способ выражения того, что делает программа на самом высоком уровне. Это отмеченные строчки, которые комментируют код. В Python они бывают двух типов: одно- и многострочные.
Однострочные комментарии в Python
Такой тип комментариев нужен для написания простых, быстрых комментариев во время отладки. Такие комментарии начинаются с символа решетки # и автоматически заканчиваются символом окончания строки (EOL).
При добавлении комментария важно убедиться, что у него тот же уровень отступа, что и у кода под ним. Например, нужно оставить комментарий к строке объявления функции, у которой нет отступа. Однако они имеются у блоков кода внутри нее. Поэтому учитывайте выравнивание при комментировании внутренних блоков кода.
Многострочные комментарии в Python
Python позволяет писать комментарии на нескольких строках. Они называются многострочными или блочными. Такой тип комментирования подходит для описания чего-то более сложного.
Этот тип комментариев нужен для описания всего последующего кода. Дальше примеры многострочных комментариев в Python.
С помощью символа #
Для добавления многострочного комментария нужно начинать каждую строку с символа решетки и одного пробела. Такой комментарий можно разбить на абзацы. Для этого достаточно добавлять пустые строки с символом перед каждым из них.
Примечание: в оригинале этот символ (#) называется octothorpe, что переводится с латинского как «восемь концов». Термин придумала группа инженеров в Bell Labs, которая работала над проектом первой сенсорной клавиатуры.
Docstring в Python
В Python есть такая особенность, как задокументированные строки (docstring). С их помощью программисты могут быстро добавлять комментарии для каждого модуля, функции, метода или класса в Python.
Задать docstring можно с помощью строковой константы. Она обязана быть первой инструкцией в определении объекта.
У docstring более широкая область применения, чем у комментария. Она должна описывать, что делает функция, а не как. Хорошей практикой считается добавление таких строк в каждую функцию программы.
Как задать docstring в Python?
Задать docstring в Python можно с помощью тройных кавычек Нужно добавить один набор в начале и еще один – в конце. Docstring также могут занимать по несколько строк.
Примечание: строки с тремя кавычками также являются docstring в Python, пусть они и могут казаться обычными комментариями.
В чем отличие между комментарием и docstring?
Строки, начинающиеся с тройной кавычки, — это все еще обычные строки, которые могут быть написаны в несколько строк. Это значит, что они все еще являются исполняемыми инструкциями. Если же у них нет метки, значит сборщик мусора уничтожит их после исполнения.
Комментарии в python
Комментарии являются неотъемлемой частью любой программы. Каждый язык программирования позволяет добавлять комментарии. Система комментирования Python очень проста.
Как писать комментарии в Python?
Примеры
Многострочный комментарий Python
Иногда невозможно разместить комментарий в одной строке. В этом случае вы можете разбить на несколько строк. Для написания многострочного комментария необходимо ставить перед каждой строкой решётку (#).
Использование строки документации
Строки документации Python (Docstring) используются для предоставления документации для функций, классов и модулей. Они заключены в пару тройных двойных кавычек («»»). Они должны быть определены сразу после объявления функции или класса.
Давайте кратко рассмотрим несколько примеров строк документации Python.
Можно ли использовать строку документации для указания длинных многострочных комментариев?
Целью строк документации Python является предоставление документации. Иногда вы заметите, что это неправильно для длинных комментариев. Однако это не рекомендуемый подход. Если вы хотите, чтобы комментарий разбился на несколько строк, просто добавьте к каждой строке символ решетки.
Многострочная строка как многострочный комментарий
Мы также можем использовать многострочную строку в качестве многострочного комментария. Они не генерируют код.
Однако это может привести к проблемам с отступами. Это также сбивает с толку, почему строка присутствует в коде без всякого использования. Поэтому лучше придерживаться обычных многострочных комментариев с использованием символа решетки.
Использование комментариев в Python
В этом руководстве мы обсудим что такое комментарии, зачем они нужны и как правильно записывать многострочные и однострочные комментарии в языке программирования Python.
Введение
По мере того, как ваши программы становятся все длиннее и сложнее, следует добавлять в код заметки, поясняющие подход, используемый вами для решения поставленной задачи.
Комментарии позволяют писать заметки и пояснять код прямо внутри программы.
Комментарии используются там, где код недостаточно понятен сам по себе. По сути, это операторы или строки, игнорируемые интерпретаторами Python.
Снабжая программу комментариями, вы делаете код более читабельным для людей, поскольку это в удобной форме поясняет назначение того или иного блока или строчки кода.
В зависимости от назначения программы, комментарии могут выполнять роль личных заметок или списков задач, которые еще предстоит выполнить, либо их можно писать для других программистов, чтобы тем было проще понять, как работает ваш код.
Как правило, лучше всего писать комментарии по ходу дела, пока вы пишете или обновляете программу – если вернуться к их написанию позже, вы можете уже не вспомнить ход своих мыслей в тот момент, и в долгосрочной перспективе такие комментарии могут оказаться менее полезными.
Создание комментария
Чтобы написать комментарий, начните строку с символа #. Python проигнорирует все, что будет написано после него. Как правило, комментарии выглядят примерно так:
Комментарии также можно размещать в конце строки:
Многострочные комментарии
В Python нет отдельного синтаксиса для многострочных комментариев. Однако, равноценного результата можно добиться, используя многострочную строку:
Если строка не привязана к какой-либо переменной, Python прочитает ее как код, но в итоге проигнорирует.
Пример использования
Иногда программисты, работающие с Python, ставят символ # перед строчкой кода, чтобы временно удалить ее из программы на время проверки. Этот прием называется «закомментировать код» и пригождается в тех случаях, когда вы пытаетесь выяснить, почему программа не работает. Закончив проверки, вы можете быстро вернуть код обратно, просто удалив поставленный перед строчкой символ #.
Заключение
Писать комментарии в коде Python – очень полезная привычка, и даже если на данный момент вы не видите в этом необходимости, то поверьте: пояснения к работе различных участков кода могут понадобиться как программистам, его читающим, так и лично вам, если вы вернетесь к работе над программой после долгого перерыва.
Это особенно полезно в том случае, если ваш код является открытым или выложен на GitHub, где другие программисты пытаются его дополнить. Подробно ознакомив их с тем, что вы уже успели сделать, вы поможете им быстрее освоиться и начать работу.
Как правильно писать комментарии в Python
Комментарии в Python – важный инструмент для программистов. Комментарии обычно используются для объяснения кода. Мы можем легко понять код, если у него есть правильное объяснение. Хороший программист должен использовать комментарии, потому что в будущем кто-то захочет изменить код, а также реализовать новый модуль; тогда это можно сделать легко.
В другом языке программирования, таком как C ++, используются: // – для однострочного комментария и / * …. * / – для многострочного комментария, но Python предоставляет однострочный комментарий. Чтобы применить комментарий в коде, мы используем решётку(#) в начале оператора или кода.
Давайте разберемся в следующем примере.
Здесь мы написали комментарий к оператору печати с помощью решетки(#). Это не повлияет на наш оператор печати.
Многострочный комментарий Python
Мы должны использовать решётку(#) в начале каждой строки кода, чтобы применить многострочный комментарий Python. Рассмотрим следующий пример.
Приведенный выше код очень удобочитаем, даже абсолютные новички могут понять, что происходит в каждой строке кода. В этом преимущество использования комментариев в коде.
Мы также можем использовать тройные кавычки(” ” ”) для многострочного комментария. Тройные кавычки также используются для форматирования строк. Рассмотрим следующий пример.
Комментарий строки документации
Комментарий к строке документации в основном используется в модуле, функции, классе или методе. Это строка документации Python. Мы объясним класс / метод в следующих руководствах.
Hello Joseph
Мы можем проверить строку документации функции с помощью атрибута __doc__.
Обычно в качестве отступа используются четыре пробела. Размер отступа зависит от пользователя, но он должен быть одинаковым во всем блоке.
Примечание. Строка документации должна быть первой в функции; в противном случае интерпретатор Python не сможет получить строку документации.
Отступы Python
Отступы Python используются для определения блока кода. Другие языки программирования, такие как C, C ++ и Java, используют фигурные скобки <>, тогда как Python использует отступы. Пробелы используются в Python как отступ.
Отступ используется в начале кода и заканчивается непреднамеренной строкой. Тот же отступ строки определяет блок кода(тело функции, цикл и т. д.)
Обычно в качестве отступа используются четыре пробела. Размер отступа зависит от пользователя, но он должен быть одинаковым во всем блоке.
Чтобы обозначить блок кода, мы выделили каждую строку блока одними и теми же пробелами.
Рассмотрим следующий пример.
Приведенный выше код, if и else – два отдельных блока кода. Оба блока кода имеют отступ в четыре пробела. Оператор print(«Задача завершена») не имеет отступа в четыре пробела и находится вне блока if-else. Если отступ используется неправильно, это приведет к ошибке IndentationError.
Однострочные и многострочные комментарии в Python
К омментарии — это пояснения к исходному тексту программы. Это может быть описание работы какого-то класса, функции или, например, значение переменной.
Чтобы ваш код был легко читаемым другими людьми, нужно придумывать очевидные имена, правильно подбирать названия функциям и правильно организовывать свой код.
Комментарии — это еще один способ сделать ваш код более читабельным. Они могут помочь не только другим людям читать и понимать ваш код, но и вам самим. Бывают ситуации, когда вы быстро пишете какой-то код, не комментируя ни строчки.
Разработчики часто забывают, как работает их собственный код. Особенно если он был написан давно.
Комментарии — это отличный способ быстро вспомнить свой код, написанный ранее.
Хороший комментарии должны быть:
Плохой комментарий описывает код, отвечая на вопрос «что делает код?». Хороший комментарий отвечает на вопрос «зачем этот код?».
О том, как правильно писать комментарии, отлично написано в книге Роберта Мартина » Чистый код «, в главе 4 «Комментарии».
PEP 8 рекомендует использовать максимум 72 символа для комментариев на одной строке. Если ваш комментарий выходит за рамки 72 символов, его рекомендуется разделить на несколько строк.
О том, как создавать однострочные и многострочные комментарии в Python, разберем ниже.
Однострочные комментарии
Чтобы написать однострочный комментарий в Python, достаточно поставить » # » перед комментарием:
# Это однострочный комментарий print(«python») # Это тоже однострочный комментарий
Python будет считать комментарием все, что находится после «#» и до конца строки.
Многострочные комментарии
Во многих языках программирования (например С++, Go, Java, JavaScript) можно создавать многострочные комментарии конструкцией вида /* */ В Python нет возможности создавать многострочные комментарии, и такая конструкция не сработает. Однако есть альтернативные решения.
Вариант #1 — писать однострочные комментарии друг за другом:
def multiline_comment_example(): # Это многострочный комментарий, оформленный # в виде однострочных комментариев, следующих # друг за другом
Вариант #2 — заключить комментарий в тройные кавычки:
«»» Это многострочный комментарий, созданный с помощью тройных кавычек «»»
Второй вариант более удобен, но есть несколько нюансов, о которых нужно помнить.
Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.