Однострочные и многострочные комментарии в Python
К омментарии — это пояснения к исходному тексту программы. Это может быть описание работы какого-то класса, функции или, например, значение переменной.
Чтобы ваш код был легко читаемым другими людьми, нужно придумывать очевидные имена, правильно подбирать названия функциям и правильно организовывать свой код.
Комментарии — это еще один способ сделать ваш код более читабельным. Они могут помочь не только другим людям читать и понимать ваш код, но и вам самим. Бывают ситуации, когда вы быстро пишете какой-то код, не комментируя ни строчки.
Разработчики часто забывают, как работает их собственный код. Особенно если он был написан давно.
Комментарии — это отличный способ быстро вспомнить свой код, написанный ранее.
Хороший комментарии должны быть:
Плохой комментарий описывает код, отвечая на вопрос «что делает код?». Хороший комментарий отвечает на вопрос «зачем этот код?».
О том, как правильно писать комментарии, отлично написано в книге Роберта Мартина » Чистый код «, в главе 4 «Комментарии».
PEP 8 рекомендует использовать максимум 72 символа для комментариев на одной строке. Если ваш комментарий выходит за рамки 72 символов, его рекомендуется разделить на несколько строк.
О том, как создавать однострочные и многострочные комментарии в Python, разберем ниже.
Однострочные комментарии
Чтобы написать однострочный комментарий в Python, достаточно поставить » # » перед комментарием:
# Это однострочный комментарий print(«python») # Это тоже однострочный комментарий
Python будет считать комментарием все, что находится после «#» и до конца строки.
Многострочные комментарии
Во многих языках программирования (например С++, Go, Java, JavaScript) можно создавать многострочные комментарии конструкцией вида /* */ В Python нет возможности создавать многострочные комментарии, и такая конструкция не сработает. Однако есть альтернативные решения.
Вариант #1 — писать однострочные комментарии друг за другом:
def multiline_comment_example(): # Это многострочный комментарий, оформленный # в виде однострочных комментариев, следующих # друг за другом
Вариант #2 — заключить комментарий в тройные кавычки:
«»» Это многострочный комментарий, созданный с помощью тройных кавычек «»»
Второй вариант более удобен, но есть несколько нюансов, о которых нужно помнить.
Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.
№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 нет отдельного синтаксиса для многострочных комментариев. Однако, равноценного результата можно добиться, используя многострочную строку:
Если строка не привязана к какой-либо переменной, Python прочитает ее как код, но в итоге проигнорирует.
Пример использования
Иногда программисты, работающие с Python, ставят символ # перед строчкой кода, чтобы временно удалить ее из программы на время проверки. Этот прием называется «закомментировать код» и пригождается в тех случаях, когда вы пытаетесь выяснить, почему программа не работает. Закончив проверки, вы можете быстро вернуть код обратно, просто удалив поставленный перед строчкой символ #.
Заключение
Писать комментарии в коде Python – очень полезная привычка, и даже если на данный момент вы не видите в этом необходимости, то поверьте: пояснения к работе различных участков кода могут понадобиться как программистам, его читающим, так и лично вам, если вы вернетесь к работе над программой после долгого перерыва.
Это особенно полезно в том случае, если ваш код является открытым или выложен на GitHub, где другие программисты пытаются его дополнить. Подробно ознакомив их с тем, что вы уже успели сделать, вы поможете им быстрее освоиться и начать работу.
Комментирование и документация кода в Python
Документирование кода на ранних этапах разработки имеет гораздо большее значение, чем может показаться на первый взгляд. Эта тема также связана с добавлением полезных комментариев к коду. Когда вы погружаетесь в разработку программы, вы можете неосознанно присвоить своим переменным и функциям весьма странные и непонятные названия. Таким образом, через некоторое время, вернувшись к коду, вы потратите огромное количество времени, пытаясь разобраться, что к чему.
Содержание статьи
Делая свой код самодокументирующимся (то есть используя информативные имена) и добавляя комментарии, вы сделаете программу более читабельной для себя и для всех остальных, кто может её использовать. Это также облегчит обновление и рефакторинг кода!
Есть вопросы по Python?
На нашем форуме вы можете задать любой вопрос и получить ответ от всего нашего сообщества!
Telegram Чат & Канал
Вступите в наш дружный чат по Python и начните общение с единомышленниками! Станьте частью большого сообщества!
Паблик VK
Одно из самых больших сообществ по Python в социальной сети ВК. Видео уроки и книги для вас!
В данной статье вы познакомитесь со следующими темами:
Давайте начнем с комментариев.
Комментарии в коде на Python
Комментарии — это подсказки, которые предназначены для вас, а не для компьютера. Комментарий это, по сути, заметка, которая объясняет, что происходит в рассматриваемой части кода. Они используются, чтобы объяснить, почему вы что-то сделали или как работает тот или иной фрагмент кода. Когда вы только начинаете программировать, будет не лишним оставлять много комментариев, к которым можно будет потом вернуться. Как только вы научитесь правильно и удобно именовать свои функции и переменные, вы поймете, что многие комментарии вам больше не нужны.
Тем не менее, комментарии все равно рекомендуется использовать. Они особенно полезны для сложного кода, который нелегко понять с первого взгляда. В зависимости от компании, в которой вы работаете, вы также можете использовать комментарии для документирования багов. Например, если вы исправили ошибку, вы можете добавить комментарий, который объясняет, в чем именно она заключается.
Далее представлен пример комментария в Python:
В приведенном выше коде показано, как создать простой комментарий. При выполнении кода, Python увидит символ # и проигнорирует весь следующий за ним текст. По сути, Python пропустит эту строку и попытается выполнить вторую.
Этот комментарий помечен как «плохой комментарий». Хотя он хорош для демонстрационных целей, но он не описывает код, который следует далее. По этой причине он не является полезным. Хорошие комментарии должны объяснять и описывать последующий код, его цели или что-то еще. Комментарии — это своеобразная документация вашего кода. Если они не предоставляют никакой полезной информации, то их следует удалить.
Вы также можете создавать комментарии на строке с кодом:
Как закомментировать и раскомментировать строки кода
В будущем вы довольно часто будете сталкиваться с таким понятием, как «закомментированный код«. Это практика добавления символа # в начале вашего кода. Таким образом, можно на всякий случай убрать какой-то кусок кода, сделав его на данный момент нерабочим.
К примеру, у вас может быть следующая строка кода:
Если вы хотите закомментировать её, это можно сделать следующим образом:
Вы можете закомментировать код в тех случаях, когда пробуете различные решения, но не хотите удалять предыдущие варианты программы. Python будет игнорировать закомментированный код, позволяя вам попробовать разнообразные пути решения задачи. Большинство редакторов кода IDE (и текстовых редакторов) предоставляют возможность выделять несколько строк и закомментировать весь блок кода.
Горячие клавиши для комментирования куса кода: (выделить нужный участок кода) + Ctrl + /
Многострочные комментарии в Python
Некоторые языки программирования, к примеру С++, предоставляют возможность создания многострочных комментариев. Для создания многострочных комментариях вы спокойно можете использовать тройные кавычки.
Далее представлен пример многострочного комментария на Python:
Давайте выясним, что это такое, и как оно используется!
Для чего используется docstring?
В Python существует концепция PEP, или Python Enhancement Proposal. PEP представляют собой предложения или новые возможности для языка Python, которые обсуждаются и согласовываются руководящим советом Python.
PEP 257 описывает соглашения о docstring. Вы можете прочитать его, если вам нужна более подробная информация. Если обобщить, то docstring — это строковый литерал, который должен быть сразу после определения названия для модуля, функции, класса или метода.
docstring создается с помощью трех двойных кавычек.
docstring можно использовать как для однострочных, так и для многострочных строк.
Далее дан пример однострочной строки:
Однострочная docstring является простой строкой текста.
Далее представлена строка docstring, используемый в функции:
В приведенном выше коде показано, как можно добавить docstring в функцию. Хорошая строка docstring описывает, что должна сделать функция.
На заметку: Хотя три двойные кавычки являются рекомендуемым стандартом, три одинарные кавычки, одни двойные кавычки и одни одинарные кавычки также работают (но одни двойные и одинарные кавычки могут содержать только одну строку, а не несколько).
Теперь давайте узнаем о создании программы в соответствии с руководством по написанию кода на Python.
PEP 8 — руководство по написанию кода на Python
Руководство по написанию кода — это документ, в котором описывается хорошая практика программирования, обычно применительно к одному языку. В некоторых компаниях существуют специальные руководства по стилю, которым сотрудники должны следовать независимо от того, какой язык программирования они используют.
Руководство по написанию кода Python было создано еще в 2001 году и получило название PEP8. В нем указаны соглашения по программированию на языке Python. За прошедшие годы текст несколько раз обновлялся.
Если вы планируете часто использовать Python, вам стоит ознакомиться с этим руководством. Оно поможет вам писать более качественный код на языке Python. Кроме того, если вы хотите внести вклад в развитие самого языка Python, ваш код должен соответствовать стилю руководства. Следование руководству сделает ваш код более легким для чтения и понимания. Это поможет вам и всем остальным, кто будет использовать ваш код в будущем.
Однако запомнить все правила может быть непросто. К счастью, некоторые бесстрашные разработчики создали определенные утилиты, которые могут помочь!
Полезные инструменты для документирования вашего кода
Существует множество инструментов, которые можно использовать для написания отличного кода. Вот всего несколько из них:
Вы можете использовать эти инструменты, чтобы найти проблемные места в вашем коде. 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. Подробно ознакомитесь с видами комментариев: однострочными и многострочными. Научитесь правильно составлять комментарии на Python.
Программирование на языке Python требует пояснений, подбора правильного названия функций, организации кода. Чтобы улучшить исходный текст программы, сделать его читабельным, используются комментарии.
Комментарии в Python – пояснения исходного текста программы. Применяются для определения работы классов, функций, значения переменной.
Примечания оставляют разработчики, для дальнейшего пересмотра строк кода. Они раскрывают смысл написанной программы. Используя комментарии или заметки, работать с кодом может другой программист.
Виды комментариев Python
Существует 2 вида комментариев языка Python: однострочные и многострочные. Применение определённого типа зависит от количества символов.
Началом однострочных комментариев является значок хештега (#). Возможно написание заметки возле оператора кода. Используется при написании дополнительных указаний, не превышающих 70-72 символов.
print(«Hello, World!») # написан текст «Привет, мир!»
Текст многострочного комментария разбивается несколькими строками. Каждая начинается с хештега. Перенос текста следующей строчки необходим, если длина заметки превышает 72 символа.
#Рассматриваемое пояснение разделено
# несколькими строчками.
Второй способ – многострочный текст выделяется тройными кавычками.
«»»
Данная функция выполняет множество действий,
она заключена в тройные кавычки.
«»»
Удобство второго способа – расположение заметки в любой части кода. Существуют нюансы работы этого способа. Размещая пояснение после функции/метода, язык программирования воспримет комментарий, как часть функции/метода.
Как оставить комментарии в Python
Начать пояснение следует с хештег символа (#), заканчивается текст концом строчки. Расположение зависит от типа комментария. Заметку можно оставить перед рабочей функцией и после неё.
# Текст находится перед рабочей частью.
print(«Hello, World!») # Заметка оставлена после определённой функции
Советы как правильно составить комментарий
Правильно составленное разъяснение поможет воспринять информацию со старого кода. С ним смогут работать другие программисты. Составляя заметку, обратите внимание на следующие факторы:
Количество символов – не пишите длинные словосочетания. Сокращайте ненужную информацию.
Актуальность – меняйте содержание после изменения кода. Старая информация запутает программиста.
Содержательность – указывайте понятную информацию. Код должен легко восприниматься человеком.
Полезность – не объясняйте простые вещи. Лишняя информация увеличит количество символов кода, сделает огромным, нечитабельным.
Не пытайтесь вместить длинные тексты в одну строчку. При большом количестве символов, разбейте их несколькими строчками.