Правила PEP 8 для написания комментариев в Python: как и зачем

Для кого эта статья:

• Python-разработчики, стремящиеся улучшить свои навыки комментарирования кода
• Студенты и обучающиеся на курсах программирования, начинающие изучать Python

• Технические менеджеры и тимлиды, интересующиеся стандартами оформления кода в команде

  Комментарии — это то, о чём разработчики вспоминают в последнюю очередь, но потом проклинают себя за их отсутствие. Представьте: вы открываете код, написанный полгода назад, и видите загадочный алгоритм без единого пояснения. Теперь умножьте эту фрустрацию на команду из 5-10 человек. Качественные комментарии — не просто хороший тон, а критический навык для профессионального Python-разработчика. Правильные комментарии следуют определённым правилам, и PEP 8 даёт чёткие указания, как их писать. 🐍

Заметили, как легко разобраться в коде, снабжённом грамотными комментариями? Именно такому подходу учат на курсе Обучение Python-разработке от Skypro. Здесь вы не только освоите синтаксис и семантику языка, но и научитесь писать код в соответствии со стандартами PEP 8, включая правила оформления комментариев. Это навык, который сразу выделит вас среди других кандидатов на позицию разработчика и сэкономит часы работы в команде.

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

Python предлагает несколько способов комментирования кода, и каждый из них имеет свои особенности и применение. Понимание базового синтаксиса — фундамент для написания хороших комментариев. 📝

В Python существует три основных вида комментариев:

• Однострочные комментарии (с символом #)
• Многострочные комментарии (с использованием тройных кавычек)
• Документационные строки или docstrings (специальный формат многострочных комментариев)

Однострочные комментарии начинаются с символа решётки (#) и продолжаются до конца строки. Это наиболее распространённый тип комментариев:

# Это пример однострочного комментария
x = 5 # Этот комментарий находится в той же строке, что и код

Для комментирования нескольких строк можно использовать символ # в начале каждой строки:

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

Многострочные комментарии создаются с помощью тройных кавычек (одинарных или двойных):

'''
Это пример
многострочного комментария
с использованием одинарных кавычек
'''

"""
А это пример
многострочного комментария
с использованием двойных кавычек
"""

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

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

def calculate_average(numbers):
"""
Вычисляет среднее арифметическое списка чисел.

Args:
numbers (list): Список числовых значений

Returns:
float: Среднее арифметическое
"""
return sum(numbers) / len(numbers)

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

Знание этих базовых синтаксических конструкций — первый шаг к написанию понятных и полезных комментариев в соответствии со стандартами PEP 8.

Однострочные и многострочные комментарии: правила PEP 8

PEP 8 — это руководство по стилю кода Python, которое включает чёткие рекомендации по оформлению комментариев. Следование этим правилам делает код более единообразным и читаемым для всего сообщества Python-разработчиков. 🔍

Алексей Петров, тимлид Python-разработки

Однажды я унаследовал проект с несколькими тысячами строк кода и отсутствием единого стиля комментирования. Разработчики использовали разные отступы, произвольное расположение символов # и непоследовательное форматирование. Нам пришлось потратить целую итерацию только на стандартизацию комментариев согласно PEP 8. После этого скорость разработки заметно выросла — новички быстрее вливались в проект, а количество вопросов "что делает этот код?" сократилось на 70%. Теперь первое, что я проверяю при code review — соответствие комментариев стандартам PEP 8.

Для однострочных комментариев PEP 8 устанавливает следующие правила:

• Комментарий должен начинаться с символа # и одного пробела после него
• Комментарии следует писать полными предложениями с заглавной буквы
• Комментарии в конце строки кода должны отделяться не менее чем двумя пробелами
• Комментарий не должен превышать 72 символа (хотя для кода максимальная длина строки — 79 символов)
• Блок связанных однострочных комментариев должен иметь одинаковый отступ

Примеры правильного оформления однострочных комментариев:

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

x = 5 # Два пробела перед комментарием в конце строки

# Блок связанных комментариев
# с одинаковым отступом
# для лучшей читаемости

Для многострочных комментариев PEP 8 рекомендует:

• Предпочтительно использовать блок однострочных комментариев вместо многострочного
• Каждая строка должна начинаться с # и пробела
• Строки должны быть разделены только одной пустой строкой при необходимости группировки
• При использовании тройных кавычек следовать тем же правилам форматирования, что и для docstrings

Пример правильного оформления блока однострочных комментариев:

# Это первый параграф комментария.
# Он содержит несколько строк текста,
# но логически это один блок информации.

# Это второй параграф, который логически
# отделен от первого.

Многострочные комментарии с тройными кавычками (хотя и менее предпочтительны по PEP 8):

"""
Это многострочный комментарий.
Его использование может быть оправдано
для временного отключения блока кода.
"""

PEP 8 также регламентирует расположение комментариев относительно кода:

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

Документационные строки (docstrings): стандарты оформления

Документационные строки (docstrings) — это особый тип комментариев, предназначенный для документирования модулей, функций, классов и методов в Python. В отличие от обычных комментариев, они доступны во время выполнения программы через атрибут __doc__. PEP 257 определяет конвенции для docstrings, которые дополняют общие рекомендации PEP 8. 📚

Основные правила для docstrings согласно PEP 257:

• Всегда использовать тройные двойные кавычки (""")
• Первая строка должна быть кратким, ясным описанием объекта
• После первой строки следует пустая строка, затем подробное описание
• Не повторять имя функции или параметры (это видно из сигнатуры)
• Заканчивать строку документации точкой

Существует несколько популярных стилей форматирования docstrings:

1. Google Style — использует секции с именами и отступами:

def calculate_area(width, height):
"""Вычисляет площадь прямоугольника.

Args:
width (float): Ширина прямоугольника.
height (float): Высота прямоугольника.

Returns:
float: Площадь прямоугольника.

Raises:
ValueError: Если width или height отрицательные.
"""
if width < 0 or height < 0:
raise ValueError("Размеры не могут быть отрицательными")
return width * height

2. NumPy/SciPy Style — похож на Google Style, но использует секции, обозначенные строками с дефисами:

def calculate_area(width, height):
"""Вычисляет площадь прямоугольника.

Parameters
----------
width : float
Ширина прямоугольника.
height : float
Высота прямоугольника.

Returns
-------
float
Площадь прямоугольника.

Raises
------
ValueError
Если width или height отрицательные.
"""
if width < 0 or height < 0:
raise ValueError("Размеры не могут быть отрицательными")
return width * height

3. reStructuredText (reST) Style — используется в Sphinx и является стандартом для документации Python:

def calculate_area(width, height):
"""Вычисляет площадь прямоугольника.

:param width: Ширина прямоугольника.
:type width: float
:param height: Высота прямоугольника.
:type height: float
:return: Площадь прямоугольника.
:rtype: float
:raises ValueError: Если width или height отрицательные.
"""
if width < 0 or height < 0:
raise ValueError("Размеры не могут быть отрицательными")
return width * height

Для различных типов объектов в Python существуют специфические рекомендации по оформлению docstrings:

Для модулей — docstring должен быть в начале файла и описывать общее назначение модуля:

"""
Модуль для работы с геометрическими фигурами.

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

Для классов — docstring должен описывать поведение класса и его публичные атрибуты:

class Rectangle:
"""
Класс для представления прямоугольника.

Атрибуты:
width (float): Ширина прямоугольника.
height (float): Высота прямоугольника.
"""

Для методов — docstring аналогичен функциям, но не нужно описывать параметр self:

def area(self):
"""
Вычисляет площадь прямоугольника.

Returns:
float: Площадь прямоугольника.
"""
return self.width * self.height

Для __init__ методов — документировать параметры конструктора, не дублируя docstring класса:

def __init__(self, width, height):
"""
Инициализирует прямоугольник с заданной шириной и высотой.

Args:
width (float): Ширина прямоугольника.
height (float): Высота прямоугольника.
"""
self.width = width
self.height = height

Независимо от выбранного стиля, важно придерживаться его последовательно во всем проекте. Многие инструменты автоматической генерации документации (Sphinx, pydoc) распознают эти форматы и создают на их основе красивую HTML-документацию.

Рекомендации PEP 8 по содержанию и стилю комментариев

Помимо синтаксических правил, PEP 8 даёт ценные рекомендации относительно содержания и стиля комментариев. Эти советы помогают писать не просто формально правильные, но действительно полезные комментарии, которые улучшают понимание кода. 🧠

Ирина Соколова, инженер по обеспечению качества кода

В прошлом году я проводила аудит кодовой базы проекта с миллионом строк кода на Python. Статистика была удручающей: 60% комментариев просто повторяли код ("incrementing counter" рядом с counter += 1), 25% устарели и содержали неактуальную информацию, и лишь 15% действительно объясняли "почему", а не "что". После внедрения правил PEP 8 по содержанию комментариев и серии обучающих сессий, через три месяца ситуация кардинально изменилась. Количество бесполезных комментариев уменьшилось на 80%, а время на адаптацию новых разработчиков сократилось вдвое. Когда комментарии объясняют неочевидные решения и бизнес-логику, а не дублируют код, ценность документации возрастает многократно.

Вот ключевые рекомендации PEP 8 относительно содержания комментариев:

• Комментарии должны объяснять "почему", а не "что" — код сам по себе показывает, что делается
• Комментировать неочевидные части кода, а не каждую строку
• Обновлять комментарии вместе с кодом
• Избегать избыточных или очевидных комментариев
• Использовать комментарии для пояснения сложных алгоритмов или бизнес-логики
• Указывать в комментариях ссылки на документацию или источники алгоритмов

Примеры хороших и плохих комментариев:

PEP 8 также дает рекомендации по стилю написания комментариев:

1. Писать ясным, грамотным языком — комментарии должны быть понятны другим разработчикам
2. Использовать полные предложения с правильной пунктуацией
3. При комментировании на английском языке следовать американскому стилю английского
4. Не использовать сокращения, которые могут быть непонятны другим
5. Быть лаконичным, но полным — комментарий должен содержать всю необходимую информацию в сжатой форме
6. Использовать маркеры TODO, FIXME, NOTE, WARNING для выделения специальных комментариев

Специальные маркеры в комментариях:

• # TODO: Реализовать проверку граничных значений — отмечает задачу, которую нужно выполнить
• # FIXME: Возможна утечка памяти при больших объемах данных — указывает на известную проблему
• # NOTE: API может измениться в будущих версиях — содержит важное замечание
• # WARNING: Не изменять порядок параметров, используется в legacy-коде — предупреждение

Многие IDE и инструменты анализа кода (например, PyCharm, VSCode с расширениями) распознают эти маркеры и выделяют их, что помогает отслеживать задачи и проблемы в коде.

PEP 8 также рекомендует использовать комментарии для временного отключения кода (вместо удаления), но предупреждает, что такие комментарии должны быть временными и содержать объяснение, почему код отключен:

# Временно отключаем валидацию из-за проблем с API поставщика
# TODO: Вернуть после исправления на стороне поставщика (ожидается 2023-05-15)
# def validate_external_data(data):
# return external_api.validate(data)

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

Распространенные ошибки при написании комментариев в Python

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

1. Комментирование очевидного кода

Одна из самых распространенных ошибок — комментирование того, что и так очевидно из кода:

# Увеличиваем counter на 1
counter += 1

# Проверяем, пуст ли список
if not my_list:
# Список пуст, выводим сообщение
print("Список пуст")

Такие комментарии только загромождают код, не добавляя ценности. Вместо этого стоит комментировать неочевидные моменты:

# Инкрементируем счетчик попыток для отслеживания
# числа запросов к нестабильному API
request_attempts += 1

# Специальная обработка для пустых списков необходима
# из-за требований в спецификации v2.3
if not items:
log_empty_list_occurrence()

2. Устаревшие комментарии

Когда код изменяется, но комментарии остаются прежними, возникает серьёзная проблема — они начинают вводить в заблуждение:

# Проверяем валидность email по регулярному выражению
def validate_email(email):
# Возвращаем True, если email валидный
return email.endswith('@example.com') # На самом деле проверяется только домен

Решение — всегда обновлять комментарии при изменении кода и периодически проводить ревизию документации.

3. Комментарии-отговорки

Иногда разработчики используют комментарии для оправдания плохого кода:

# Я знаю, что это некрасиво, но работает
def calculate_total(items):
t = 0
for i in range(len(items)):
t = t + items[i].p * items[i].q
return t

Вместо таких комментариев лучше потратить время на улучшение кода:

def calculate_total(items):
"""Вычисляет общую стоимость всех позиций."""
return sum(item.price * item.quantity for item in items)

4. Избыточное форматирование

Некоторые разработчики слишком увлекаются украшением комментариев:

###############################################
# #
# ФУНКЦИЯ ДЛЯ ОБРАБОТКИ ДАННЫХ ПОЛЬЗОВАТЕЛЯ #
# #
###############################################

PEP 8 рекомендует более сдержанный стиль. Для выделения разделов достаточно простого форматирования:

# Обработка данных пользователя
# ----------------------------------

5. Отсутствие комментариев к публичному API

Функции и классы, которые используются другими разработчиками, должны иметь четкую документацию в виде docstrings. Отсутствие такой документации — серьёзная ошибка:

def process_data(data, options=None):
# Здесь должен быть docstring!
if options is None:
options = {}
# ...

Правильный подход — всегда документировать публичный API:

def process_data(data, options=None):
"""
Обрабатывает входные данные с применением указанных опций.

Args:
data (dict): Словарь с входными данными.
options (dict, optional): Настройки обработки. По умолчанию {}.

Returns:
dict: Обработанные данные.

Raises:
ValueError: Если data не является словарем.
"""
if options is None:
options = {}

6. Непоследовательный стиль

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

# это комментарий в одном стиле
# А это – в другом стиле.
'''А это вообще использование многострочной строки вместо #'''

Решение — придерживаться единого стиля во всем проекте, предпочтительно описанного в PEP 8.

7. Использование комментариев вместо системы контроля версий

Нередко встречаются комментарии, хранящие историю изменений:

# 2022-05-10: Добавлена поддержка CSV
# 2022-06-15: Исправлена ошибка с кодировкой
# 2022-07-01: Добавлен параметр encoding

Для этого существуют системы контроля версий, такие как Git. Комментарии должны объяснять текущее состояние кода, а не его историю.

8. Информационный шум

Слишком много комментариев может быть так же плохо, как и их отсутствие:

# Создаем список
items = []
# Перебираем числа от 1 до 10
for i in range(1, 11):
# Добавляем число в список
items.append(i)
# Выводим список
print(items)

Этот код не требует комментариев, так как он и так понятен.

9. Неинформативные docstrings

Часто встречаются docstrings, которые не предоставляют полезной информации:

def calculate_area(width, height):
"""Функция для вычисления площади.""" # Неинформативно
return width * height

Лучший подход — включать в документацию полезные детали:

def calculate_area(width, height):
"""
Вычисляет площадь прямоугольника.

Args:
width (float): Ширина прямоугольника в метрах.
height (float): Высота прямоугольника в метрах.

Returns:
float: Площадь прямоугольника в квадратных метрах.
"""
return width * height

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

Правильное комментирование кода на Python — это баланс между излишней детализацией и полным отсутствием пояснений. Хороший комментарий объясняет "почему", а не "что", соответствует стандартам PEP 8 и PEP 257, и актуален относительно кода. Помните: каждый раз, когда вы пишете комментарий, задайте себе вопрос — действительно ли он прояснит непонятные аспекты для другого разработчика? Если ответ положительный, ваш комментарий заслуживает места в коде. Качественные комментарии — это инвестиция в будущее проекта и показатель вашего профессионализма как Python-разработчика.

Читайте также

• Лучшие книги по Python: от основ до профессионального уровня
• Интеграция GPT в веб-разработку на Python: создание умных сайтов
• Python REPL: мощный инструмент для быстрой разработки и тестирования
• Работа с файлами Python: основы, чтение, запись и обработка ошибок
• Словарь в JSON: полное руководство по преобразованию в Python
• Настройка Python в IntelliJ IDEA: пошаговое руководство для разработчиков
• Garbage collector в Python: механизмы управления памятью и оптимизация
• Командная строка Python: как создать гибкие CLI-интерфейсы
• 7 ключевых методов для эффективной работы со списками в Python
• Разработка REST API клиентов на Python: базовые принципы и лучшие практики