Почему комментарии часто излишни в коде? 🤔

Тебе наверняка говорили: “Комментируй свой код!”. Но есть секрет: хороший код объясняет себя сам. Комментарии нужны редко, и часто они вредят больше, чем помогают.

🎯 Главная идея

Код должен быть понятным БЕЗ комментариев. Если нужен комментарий чтобы объяснить что делает код — значит код написан неправильно!

❌ Плохой пример (с комментариями)

# Вычисляем площадь прямоугольника
a = 5
b = 10
s = a * b  # умножаем стороны
print(s)   # выводим результат

Читается сложно. Нужно смотреть и код, И комментарии.

✅ Хороший пример (без комментариев)

width = 5
height = 10
rectangle_area = width * height
print(rectangle_area)

Читается легко! Названия переменных объясняют всё. Комментарии не нужны.

🚫 5 типов ВРЕДНЫХ комментариев

1. “Очевидные” комментарии

# ❌ ПЛОХО: Комментарий говорит то же, что и код
age = age + 1  # увеличиваем возраст на 1

# ✅ ХОРОШО: Просто понятное имя
user_age += 1

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

# ❌ ПЛОХО: Комментарий врёт! (температура уже в цельсиях)
temperature_celsius = 25  # температура в фаренгейтах

# ✅ ХОРОШО: Комментарий не нужен
temperature_celsius = 25

Проблема: Код обновляется, а комментарии забывают обновлять. Они начинают врать!

3. “Извиняющиеся” комментарии

# ❌ ПЛОХО: Признаёшься что код плох
# TODO: переписать этот костыль
# FIXME: тут баг, но работает
x = calculate_weird_stuff()  # не знаю как это работает

# ✅ ХОРОШО: Просто исправь код вместо комментариев!
discount_amount = calculate_discount(price, promo_code)

4. “Закомментированный код”

# ❌ ПЛОХО: Старый код мешает читать новый
def launch_rocket():
    # fuel = 100
    # if fuel > 50:
    #     print("OK")
    fuel_level = get_fuel_tank_percentage()
    if fuel_level >= 75:
        print("🚀 Готовы к старту!")

Проблема: Непонятно зачем это! Использовать? Удалить? Для чего оставили?

Решение: Удаляй старый код без страха. У тебя есть Git — всегда можно вернуть.

5. “Шумовые” комментарии

# ❌ ПЛОХО: Комментарий на каждую строку
# Функция приветствия
def greet():
    # Создаём переменную имени
    name = input("Как тебя зовут? ")
    # Выводим приветствие
    print(f"Привет, {name}!")

# ✅ ХОРОШО: Код читается как текст
def greet_user():
    user_name = input("Как тебя зовут? ")
    print(f"Привет, {user_name}!")

✅ Когда комментарии НУЖНЫ

1. Объяснение “почему”, а не “что”

# Используем sleep чтобы система успела загрузиться
# (по документации требуется минимум 2 секунды)
time.sleep(2)

# Умножаем на 1.2 потому что библиотека возвращает значение в килобайтах
# а нам нужно с учётом служебных данных (+20%)
file_size_with_overhead = raw_size * 1.2

2. Сложная математика или алгоритмы

# Формула Герона для площади треугольника: S = √(p(p-a)(p-b)(p-c))
# где p - полупериметр
semi_perimeter = (a + b + c) / 2
area = (semi_perimeter * (semi_perimeter - a) * (semi_perimeter - b) * (semi_perimeter - c)) ** 0.5

3. Важные предупреждения

# ВНИМАНИЕ: Этот метод отправляет РЕАЛЬНЫЕ деньги!
# Вызывай только после подтверждения пользователя
def process_payment(amount):
    ...

4. TODO для себя

# TODO: Добавить проверку отрицательных чисел
def calculate_discount(price):
    return price * 0.9

🎓 Правила чистого кода

Правило 1: Говорящие имена

# ❌ Плохо
t = 25

# ✅ Хорошо
temperature_celsius = 25

Правило 2: Короткие функции

# ❌ Плохо: Функция на 50 строк с комментариями
def do_everything():
    # ... 50 строк кода ...

# ✅ Хорошо: Разбей на маленькие функции с понятными именами
def validate_input():
    ...

def calculate_result():
    ...

def display_output():
    ...

Правило 3: Один уровень абстракции

# ❌ Плохо: Смешаны детали и общая логика
def launch():
    fuel = 100
    if fuel > 50:  # проверка топлива
        time.sleep(1)  # таймер обратного отсчёта
        print("Старт!")

# ✅ Хорошо: Каждая функция на своём уровне
def has_enough_fuel():
    return get_fuel_level() > MINIMUM_FUEL_THRESHOLD

def countdown():
    time.sleep(COUNTDOWN_DURATION)

def launch():
    if has_enough_fuel():
        countdown()
        print("🚀 Старт!")

💡 Практические советы

Вместо комментариев:

1. Переименуй переменную — a → user_age
2. Выдели в функцию — дай ей говорящее имя
3. Используй константы — if score > 100: → if score > MAXIMUM_SCORE:
4. Разбей на шаги — длинный код → несколько коротких функций

Проверь себя:

• Ты читаешь код вслух — звучит ли он как предложение на русском?
• Твой друг смотрит на код — понимает ли он что происходит БЕЗ твоих объяснений?
• Комментарий дублирует код? — УДАЛИ комментарий!

🎯 Итог

Запомни: Комментарии — это признание что твой код непонятен. Лучший комментарий — это его отсутствие!