Создание многострочных комментариев в Python: аналог /

Быстрый ответ

В Python многострочные комментарии обозначаются при помощи тройных кавычек """...""":

"""
Python интерпретатор проигнорирует этот блок текста, 
рассматривая его как строковой литерал, а не исполняемый код.
"""

Однако важно понимать, что подобные блоки – это строковые литералы, а не собственно комментарии. Однострочные комментарии вводятся с помощью символа #. Текст, следующий за ним, Python интерпретирует как комментарий.

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

Подход к комментированию в Python

Особенности комментирования в Python

В стремлении к простоте Python упрощает встроенный механизм для многострочных комментариев, отличный от тех, что используются в языках типа Java или C (/*...*/). Это решение направлено на повышение читаемости и простоты кода.

Роль тройных кавычек в Python

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

Выключение блоков кода

Однострочные комментарии, начинающиеся на #, адекватны для временного отключения блоков кода. Единобразие комментариев соответствует рекомендациям стандарта PEP 8 и предусматривает использование горячих клавиш текстовых редакторов.

Документирование кода и Docstrings

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

Искусство комментирования

Важность отступов

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

Читаемость кода

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

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

Предпочитайте текстовые редакторы вроде Notepad++, gVim или Emacs, которые предлагают удобные функциональные возможности для комментирования кода, например, горячие клавиши для упрощения и ускорения этого процесса.

Визуализация

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

# Однострочное 'одеяло' (`#`)
# Python не исполнит эту строку, так как она "скрыта" под символом комментария.

# Многострочное 'одеяло' (`"""` или `'''`)
"""
Python пропустит этот блок: он укрыт "многострочным одеялом".
Также и эту строку игнорирует!
"""

🛌 Каждое "одеяло" – это комментарий, который делает код под ним неактивным. 🛌

# Методы комментирования в Python:
| Синтаксис | Тип комментария    | Визуализация            |
| --------- | ----------------   | ----------------------- |
| `#`       | Однострочный       | индивидуальное одеяло 🛌 |
| `"""`     | Начало многострочного | верх большого одеяла 🛏️  |
| ...код...  | (спящий код)       | ...zzz...               |
| `"""`     | Конец многострочного | низ большого одеяла 🛏️ |

...так код получает возможность "вздремнуть".

Рекомендации по комментированию для Python-программистов

Избегайте излишнего комментирования

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

Комментарии, раскрывающие суть

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

Документируйте код при помощи docstrings

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

Полезные материалы

1. PEP 8 – Руководство по стилю кода Python — Стилистическое руководство по Python, включая правила блочного комментирования.
2. PEP 257 – Конвенции Docstring — Стандартные требования для многострочных docstrings в Python.
3. Как оформлять комментарии в Python (Руководство) – Real Python — Глубокий анализ особенностей комментирования в Python.
4. 2. Лексический анализ — Документация Python 3.12.1 — Официальное описание лексической структуры языка Python, включая раздел о комментариях.
5. Стиль кодирования — Руководство для начинающих Python — Лучшие практики написания аккуратного кода на Python, в том числе рекомендации по комментированию кода.
6. Комментирование в Python: важность, типы и правильное использование – GeeksforGeeks — Обзор комментирования в Python и рекомендаций по его применению.
7. Как комментировать в Python – W3Schools — Базовые правила оформления комментариев в Python для начинающих.