Serguey Asael Shinder – IT Professional

Автор: Serguey Shinder

Колись я пишався своїми коментарями. Я щедро пояснював кожен складний шматок коду, вважаючи, що дбаю про наступного читача. Файли рясніли поясненнями: що робить ця функція, чому цей цикл влаштований саме так, що означає ця змінна. Мені здавалося, що це ознака дбайливого інженера.

Перелом стався, коли я натрапив на коментар, який брехав. Він описував, що код робить одне, а код давно робив інше — хтось змінив логіку й забув оновити пояснення. І я зрозумів страшну річ: коментар, який розходиться з кодом, гірший за відсутність коментаря. Він активно вводить в оману. А розходяться вони постійно, бо код змінюють, а слова поряд — ні.

Тоді я почав дивитися на свої коментарі інакше. Багато з них існували лише тому, що сам код був незрозумілий. Я пояснював словами те, що мав би зробити ясним у самому коді. Заплутана функція з абзацом пояснень — це не дбайливість. Це визнання, що функція заплутана, обгорнуте виправданням замість виправлення.

Тож замість писати коментар я почав переписувати код. Дати змінній ім’я, яке саме все пояснює. Розбити хитрий рядок на кілька простих. Зробити очевидний шлях справді очевидним. І щоразу, коли мені це вдавалося, коментар ставав непотрібним — його можна було просто видалити, бо код тепер говорив сам за себе.

Найкращий коментар, який я написав за останні роки, — це той, який я зрештою видалив, бо переписав код так, що пояснення більше не було потрібне. Я перестав пояснювати заплутаний код і почав робити його ясним. Коментарі брешуть із часом. Ясний код — ні.

– Serguey Asael Shinder