Перейти к содержимому

Как быстро закомментировать в питоне

  • автор:

Комментирование кода в Python (Урок №5)

Прежде чем двигаться далее, изучим короткую, но важную тему комментирования кода в Python.

Бывает так, что программист написал программу, отложил ее в сторону на несколько дней, а потом с удивлением понимает, что уже и не помнит, что там нагородил =)

На самом деле, это частая ситуация. Я сам регулярно возвращаюсь к своим старым программам и радуюсь (но не всегда), что комментировал собственный код.

И, как результат, я быстрее понимаю, что сам и написал =)

Что такое комментирование кода?

Если кратко, то это поясняющие записи, к тем или иным командам. Можно провести аналогию с заметками на полях книги.

Но прежде чем продолжить далее, отмечу, что можете посмотреть видео (в нем больше информации, по понятным причинам), или прочитать текстовую версию чуть ниже.

Не забудьте подписаться на мой Видеоканал в Яндекс.Дзен.

Как комментировать код в Python?

Например, вот так:

При этом, интерпретатор Python игнорирует все символы, которые находятся после # и до конца строки.

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

Если мы запустим код выше на выполнение, то получим 8 (результат сложения переменных d = b + c).

Но так как две строки

закомментированы, то они не будут исполняться интерпретатором. И мы не увидим на экране, какие значения у переменных b и c.

Это полезная фича, когда тестируется программа, или ищут ошибки в коде.

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

При этом поясняющие комментарии лучше оставить.

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

Сами потом себя похвалите за предусмотрительность, когда через какое-то время вернетесь к тому ,что написали.

Как сразу закомментировать много строк кода?

Бывает так, что нужно сразу закомментировать много строк кода, которые временно нужно исключить. Если вручную ставить в начале каждой строки знак #, то можно быстро разозлиться.

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

Например, если используете PyCharm, то достаточно выделить нужный блок кода и нажать сочетание клавиш CTRL + /

Если нужно раскомментировать много строк кода, то опять выделяем нужные строки и снова нажимаем сочетание клавиш CTRL + /.

How to Make a Block Comment in Python | Python Tutorial

Sanjay Priyadarshi

Programming languages like C++, Java, and C have built-in to support block comments. When you use those programming languages, you can use multi-line comments if you want.

With the python programming language, there is no built-in mechanism to block comments.

You have to use different conventions to block comments in python.

You can use comments to explain your Python code.

Comments can make your code more readable.

Here we will discuss how you can add block comments in python.

Block comment in Python

Python ignores and does not evaluate comments present in the codebase, making it more readable.

If you’ve ever used a programming language other than Python, you should be aware of two types of code comments.

The first is called a single-line comment, and the second type of comment is called a block comment.

A single-line comment is the most basic way to document your code. With single-line comments, you can reduce the size of your code documentation.

Block comments are used to comment on paragraphs of text. With the help of the block comment, a larger functional documentation can be made.

In the block comment, you must provide the start and end symbols. Anything between those symbols is not evaluated by the programming language.

Use multiple single-line comments to add a block comment in python

If you’re a Python programmer, you may have learned that hash mark (#) comments are the easiest way to write comments in your code base.

Hash sign comments allow developers to add single-line comments and can help you document the code you write.

The compiler ignores all text that follows a hash sign. This is why any programmer can use the hash sign to write notes for other programmers.

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

В Python, для однострочных комментариев используется символ # . Но если нужно закомментировать большой блок кода, то приходится приписывать # в начале каждой строки. Это очень неудобно при отладке.

Есть ли какая-то возможность использовать многострочные комментарии (аналог /* . */ из Си) в Python?

UPD:

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

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

Строковые литералы, заключенные в тройные кавычки, могут содержать:

  • кавычки ( » )
  • апострофы ( ‘ )
  • docstring комментарии ( «»»func desc»»» )
  • переводы строк

В тоже время, стоит помнить, что такой строковый литерал не должен содержать внутри символов »’ . Это требование аналогично запрету на последовательность символов */ внутри многострочного комментария Си.

Кстати, этот же хак, предлагает использовать создатель языка Python в одном из своих твитов.

В тоже время, как верно отметил @jfs, руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.

Руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.

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

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

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

Закомментированный код не должен добавляться в систему контроля версий, поэтому для временных изменений, которые не переживут одну сессию редактирования кода, один клавишный аккорд (например, M-; в Emacs), как правило, достаточен, чтобы закомментировать/раскомментировать кусок кода.

«»»multiline string literal»»» не является многострочным комментарием в Питоне. Это просто строковая константа, которая позволяет использовать буквальные символы новой строки без экранирования (такого как \n ). Часто используется для описаний модулей, классов, функций/методов прямо в коде:

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

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

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *