Чистый код и полезные комментарии 🧹

Представь рабочий стол после большого проекта: инструменты нужны, а пустые коробки и старые черновики уже мешают. С кодом происходит то же самое. Когда программа заработала, стоит убрать следы экспериментов и сделать её понятной для следующего читателя — даже если этим читателем завтра будешь ты сам.

Понятные имена вместо загадок

# Непонятно
h = 20
d = 0.3

# Понятно
flight_height = 20
frame_delay = 0.3

Хорошее имя рассказывает, что хранится в переменной. Для обычных переменных Python-разработчики используют snake_case.

Настройки, которые не планируется менять во время выполнения, принято записывать в UPPER_CASE:

FLIGHT_HEIGHT = 20
RESET_COLOR = '\033[0m'

Разделяй код на смысловые блоки

Пустая строка помогает увидеть структуру файла:

import time

FLIGHT_HEIGHT = 20
FRAME_DELAY = 0.3

print('Подготовка к запуску')
time.sleep(FRAME_DELAY)

Обычно сначала идут импорты, затем настройки и данные, а после них — команды программы.

Удаляй следы экспериментов

После проверки в файле могут остаться старые формулы, повторные команды и закомментированные версии кода:

# delay = 1
# delay = 0.5
delay = 0.3

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

Комментарий должен объяснять причину

Комментарий, который просто повторяет код, не помогает:

# Ждём одну секунду
time.sleep(1)

Полезный комментарий объясняет решение, которое нельзя понять по одной команде:

# CodeHS требуется время, чтобы успеть отрисовать новый кадр.
time.sleep(0.1)

Комментарии особенно полезны для ограничений среды, необычных формул и причин, по которым выбран неочевидный вариант. Главное — обновлять комментарий вместе с кодом.

Не ломай программу во время уборки

Меняй по одному небольшому фрагменту:

1. Удали одну ненужную строку.
2. Запусти программу.
3. Убедись, что результат не изменился.
4. Переходи к следующему фрагменту.

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

Быстрая проверка

• Имена объясняют назначение переменных.
• Настройки собраны рядом и записаны в UPPER_CASE.
• Рабочие переменные используют snake_case.
• В файле нет старых и дублирующихся вариантов кода.
• Комментарии объясняют причины, а не произносят команды вслух.
• После уборки программа работает так же, как раньше.

Чистый код — не самый короткий и не тот, где совсем нет комментариев. Это код, в котором легко найти нужное место и безопасно сделать следующее изменение.