Коментари, които лъжат, и такива, които помагат

Код на:JavaC#PythonJavaScript

Накратко: Добрият коментар казва защо кодът е такъв; коментар, който преразказва кода, остарява и започва да лъже, затова се заменя с добро име или функция.

Проблем

Коментарът, на който всички вярват

Магазинът дава безплатна доставка от определена сума нагоре. Миналата пролет прагът беше 50 € и коментарът над delivery_fee казва точно това. После маркетингът го вдигна на 100 €. Числото в кода е сменено. Коментарът не е.

Тази есен колега пише банера в кошницата. Чете коментара, не кода, и слага 50:

# Безплатна доставка за поръчки от 50 € нагоре.
def delivery_fee(total):
    if total >= 100:
        return 0
    return 4.90


def banner(total):
    if total >= 50:
        return "Доставката е безплатна!"
    return f"Още {50 - total:.2f} € до безплатна доставка"

total = 60
print(f"Кошница: {total:.2f} €")
print(banner(total))
print(f"Доставка: {delivery_fee(total):.2f} €")

Изход

Кошница: 60.00 €
Доставката е безплатна!
Доставка: 4.90 €

Клиент с кошница за 60 € чете „Доставката е безплатна!“ и после плаща 4,90 € за доставка. Поддръжката гледа delivery_fee и не намира грешка: функцията прави точно каквото пише в кода. Грешката е в текст, който никой не пуска.

Виж го

Кодът продължи, коментарът остана

Ето какво стана, стъпка по стъпка:

# Безплатна доставка за поръчки от 50 € нагоре.
def delivery_fee(total):
    if total >= 100:
        return 0
    return 4.90


def banner(total):
    if total >= 50:
        return "Доставката е безплатна!"
    return f"Още {50 - total:.2f} € до безплатна доставка"


total = 60
print(f"Кошница: {total:.2f} €")
print(banner(total))
print(f"Доставка: {delivery_fee(total):.2f} €")

Стъпка по стъпка, с думи

1. Първата версия: коментарът (ред 1) и проверката (ред 3) казват едно и също: 50 €.
2. Прагът става 100 €. Някой сменя числото на ред 3, а коментара не го пипа. Компилаторът проверява кода. Коментарите не ги проверява никой.
3. Колега пише банера. Чете коментара, не кода, и на ред 9 слага 50.
4. Кошница за 60 €. Банерът пита своя праг: 60 ≥ 50, значи „Доставката е безплатна!“.
5. Таксата пита истинския праг: 60 < 100, значи доставката е 4,90 €.
6. Клиентът чете „безплатна“ и плаща 4,90 €. Лъжата е на ред 1. Бъгът, който тя роди, е на ред 9.

Компилаторът проверява всеки ред код. Тестовете проверяват какво прави кодът. Коментара не го проверява никой: той е текст до кода, и при всяка промяна на кода може да остане назад. Такъв коментар се казва остарял коментар (stale comment). Той е по-лош от липсващ, защото звучи уверено.

Идеята

Нека кодът го каже сам

Прагът е правило на магазина, а правилото е на две места: в кода на таксата и в главата на всеки, който е чел коментара. Дай му име, и двете функции питат името:

FREE_DELIVERY_FROM = 100


def delivery_fee(total):
    if total >= FREE_DELIVERY_FROM:
        return 0
    return 4.90


def banner(total):
    if total >= FREE_DELIVERY_FROM:
        return "Доставката е безплатна!"
    return f"Още {FREE_DELIVERY_FROM - total:.2f} € до безплатна доставка"

total = 60
print(f"Кошница: {total:.2f} €")
print(banner(total))
print(f"Доставка: {delivery_fee(total):.2f} €")

Изход

Кошница: 60.00 €
Още 40.00 € до безплатна доставка
Доставка: 4.90 €

Коментарът вече не трябва: името казва същото. Разликата е, че името не може да остане назад. Ако прагът стане 150 €, сменяш един ред и banner получава новия праг. Ако някой изтрие константата, програмата спира да се компилира (в Python спира при първото извикване с грешка, че името го няма).

Това е правилото на урока за имената (Имена в кода): преди да напишеш коментар, провери дали име не може да каже същото.

Пробвай

Предвиди изхода

Хотелът продава нощувки онлайн. Какво печата програмата?

# Цената с ДДС 20%.
def with_vat(net):
    return net * 1.09


print(f"{with_vat(100):.2f} €")

Отговор

120.00 €

109.00 €

100.00 €

Провери

Коментарът казва 20%, а кодът умножава по 1.09. Нощувките в България са с ДДС 9%, и някой е сменил числото, без да пипне коментара. Програмата слуша кода.

Виж го

Коментари, които повтарят кода

Всеки коментар тук казва същото като реда под него:

# Цената на продукта.
price = 25.00
# Количеството.
quantity = 3
# Умножаваме цената по количеството.
total = price * quantity
# Отпечатваме сумата.
print(f"Общо: {total:.2f} €")

Изход

Общо: 75.00 €

Четеш всичко два пъти и не научаваш нищо ново. По-лошото е, че свикваш да прескачаш коментарите, и прескачаш и онзи, който е важен. Изтрий ги. Програмата е същата, а изходът също.

Виж го

Коментар вместо име, коментар вместо функция

Тук коментарите обясняват неща, които кодът крие:

n = 7  # брой поръчки на клиента
s = 420  # оборот на клиента в евро
# Клиентът е VIP: поне 5 поръчки или поне 500 € оборот.
if n >= 5 or s >= 500:
    print("VIP отстъпка: 10%")

Изход

VIP отстъпка: 10%

Коментарът до n е там, защото името не казва нищо. Дай му името от коментара: orders. Коментарът над if описва правило. Правилото с име е функция:

def is_vip(orders, spent):
    return orders >= 5 or spent >= 500

orders = 7
spent = 420
if is_vip(orders, spent):
    print("VIP отстъпка: 10%")

Изход

VIP отстъпка: 10%

Изходът е същият, а коментари няма. Редът if се чете като изречение. Ако правилото стане „поне 10 поръчки“, сменяш тялото на is_vip и всяко място, което я вика, получава новото правило. Как се отделя такава функция, е в урока Функции.

Виж го

Закоментиран код и TODO без собственик

def confirm(order_id):
    send_email(order_id)
    # send_sms(order_id)
    # if sms_enabled:
    #     send_sms(order_id)
    # TODO: оправи

Изход

Имейл за поръчка #1063

Изпраща ли се SMS? Никой не знае дали е спрян нарочно, временно или по грешка, и никой не смее да го изтрие. Така закоментираният код живее години. Изтрий го: старият код е в историята на git и се връща с една команда.

TODO без име и без срок е желание, което никой не притежава. Добрият TODO казва кой, кой тикет и кога:

def confirm(order_id):
    send_email(order_id)
    # TODO(maria, SHOP-412): добави SMS, когато новият доставчик мине тестовете.

Изход

Имейл за поръчка #1063

Още по-добре е задачата да е в тикета, а в кода да остане само връзката.

Идеята

Какво казва добрият коментар

Кодът казва какво прави. Добрият коментар казва нещо, което кодът не може да каже:

# Куриерът взима 30% от таксата, закръглено надолу до цент.
# Така е в договора с него (т. 4.2), затова тук няма round().
def courier_share_cents(fee_cents):
    return fee_cents * 30 // 100

fee = 495  # SHOP-388: куриерът праща таксата в центове, не в евро.
print(f"Куриер: {courier_share_cents(fee) / 100:.2f} €")

Изход

Куриер: 1.48 €

Тук има три такива неща:

• защо: закръгляне надолу изглежда като грешка, докато не прочетеш, че така е в договора. Без коментара някой ще го „поправи“;
• къде да научиш повече: тикетът SHOP-388 разказва историята, която в кода не се събира;
• мерната единица, която типът не казва: центове, не евро. В урока за миризмите ще видиш как това отива в самия тип.

Още едно: предупреждение като „Бавно: всяко извикване е заявка към банката, около 300 ms. Не го викай в цикъл.“ Такъв коментар пести на следващия човек един ден в търсене.

И добрият коментар може да остарее. Но остарява рядко, защото не повтаря кода: договорът не се сменя всеки път, когато сменяш функцията.

По-точно, за любопитните

git blame показва кога е писан всеки ред. Ако кодът под коментара е по-нов от самия коментар, бъди нащрек: някой е пипнал кода и може да не е стигнал до коментара.

Виж го

Документация за този, който вика

Който вика delivery_fee от друг модул, не иска да чете тялото ѝ. Иска да знае какво да подаде и какво ще получи. За това всеки език има документационен коментар, който редакторът показва, когато задържиш мишката над името:

FREE_DELIVERY_FROM = 100


def delivery_fee(total: float) -> float:
    """Таксата за доставка на поръчка.

    total е сумата на стоките в евро, без доставката. Връща 0
    от FREE_DELIVERY_FROM нагоре, иначе таксата на куриера.
    """
    if total >= FREE_DELIVERY_FROM:
        return 0
    return 4.90

print(delivery_fee.__doc__.splitlines()[0])
print(f"Доставка при 60 €: {delivery_fee(60):.2f} €")
print(f"Доставка при 120 €: {delivery_fee(120):.2f} €")

Изход

Таксата за доставка на поръчка.
Доставка при 60 €: 4.90 €
Доставка при 120 €: 0.00 €

Това е docstring: низ, който е първият ред в тялото на функцията. Той не е коментар, а част от функцията: програмата го чете като delivery_fee.__doc__, а help(delivery_fee) го показва в конзолата. total: float и -> float са подсказки за типа (type hints): Python не ги проверява при пускане, а редакторът и инструменти като mypy го правят.

Документацията казва договора: какво значи параметърът и в какви единици е, какво се връща и кога има грешка. Не казва как е направено отвътре. Числата от кода не се повтарят в нея: вместо „от 100 €“ пише името на константата, за да не остане назад.

По-точно, за любопитните

Подсказките за типа също са документация, но проверима: mypy пада, ако подадеш "60" на delivery_fee. PEP 257 описва как се пише docstring: първият ред е едно изречение, после празен ред и подробностите.

Попълни липсващото:

FREE_DELIVERY_FROM = 100


def delivery_fee(total: ) -> float:
    """Таксата за доставка на поръчка.

    total е сумата на стоките в евро, без доставката. Връща 0
    от FREE_DELIVERY_FROM нагоре, иначе таксата на куриера.
    """
    if total >= FREE_DELIVERY_FROM:
        return 0
    return 4.90

Провери

Пробвай

Намери грешката

Магазинът праща имейл „Как ти се стори поръчката?“ ден след доставката. Последната поръчка на клиента е от 24.10, а имейлът пита за тази от 12.10:

orders = ["2026-10-19 #1057", "2026-10-24 #1063", "2026-10-12 #1041"]
print(reminder(orders))

Изход

Как ти се стори поръчка 2026-10-12 #1041?

Кой ред взима грешната поръчка?

Избери реда с грешката.

1# Връща поръчките от най-новата към най-старата.2def history(orders):3 return sorted(orders)456def reminder(orders):7 latest = history(orders)[0]8 return f"Как ти се стори поръчка {latest}?"

Провери

Упражнение

Изчисти коментарите

Реши задачата в редактора си.

Отстъпка за лоялни клиенти. Във функцията има коментар, който лъже, коментар, който повтаря кода, закоментиран ред и TODO без собственик:

# Отстъпка за лоялни клиенти: 5%.
def loyalty_total(total, orders):
    # ако клиентът има повече от 10 поръчки
    if orders >= 20:
        # total = total * 0.95
        total = total * 0.90  # намаляваме total
    # TODO: закръгляне
    return total

print(f"Сума: {loyalty_total(200, 25):.2f} €")
print(f"Сума: {loyalty_total(200, 12):.2f} €")

Изход

Сума: 180.00 €
Сума: 200.00 €

Изчисти я: махни шума и мъртвия код, замени числата с имена, а TODO или направи, или му дай собственик и тикет. Изходът трябва да остане същият.

Още задачи

• Документирай подредбата. Напиши документационен коментар за oldest_first от задачата с поръчките: какво приема, какво връща и в какъв ред.
• Банерът на 99,99 €. Пусни банера от картата „Нека кодът го каже сам“ с кошница за 99,99 € и за 100 €. Провери, че двете функции са съгласни и на самия праг.
• Твоят проект. Отвори последния си проект и намери три коментара. За всеки реши: повтаря ли кода, казва ли защо, или лъже?

Тест

Провери се

1. Коментарът над функцията казва едно, а кодът под него прави друго. На кое вярваш?

На кода: той е това, което се изпълнява. После поправяш или махаш коментараНа коментара: някой го е написал нарочноНа никое, докато не попиташ автора

2. Какво не е наред с „count += 1 # увеличава count с 1“?

Нищо, коментарите винаги помагатТрябва да е на отделен редПовтаря кода с други думи: четеш два пъти, а не научаваш нищо

3. Във функцията има закоментиран ред „# send_sms(order)“. Какво правиш?

Оставяш го, може да потрябваМахаш коментара, за да се изпълниИзтриваш го. Ако потрябва, git го пази

4. Кой коментар си заслужава?

# Закръгляме надолу: така е в договора с куриера (т. 4.2).# Функция за куриера.# Умножаваме по 0.30.

5. Кой TODO ще бъде направен някога?

# TODO(maria, SHOP-412): добави SMS, когато новият доставчик мине тестовете.# TODO: да се помисли# TODO: оправи

Провери

Започни урока отначало

Свързани уроци

• Нужно отпреди: Общото за всички: атрибути на класа · Списъци: append, remove и sort · Имена в кода · Функции: една работа, малко параметри, без скрити странични ефекти
• Продължава в: Миризмите: дълъг метод, голям клас, дублиране, примитиви вместо типове, дълга верига if · Упражнение: разхвърлян клас, изчистен стъпка по стъпка
• Задачи по темата: Чист код и refactoring