Зрозумілий код для вайбкодера: імена, DRY, KISS

Що таке зрозумілий код простими словами

Уяви два холодильники. У першому все підписано: «соуси», «сніданки», «не чіпати - це на свято». Відкрив - і за три секунди знайшов те, що шукав. А в другому двадцять однакових контейнерів без жодного підпису. Щоб знайти йогурт, ти відкриваєш кожен і нюхаєш. Інколи знаходиш те, що нюхати вже точно не варто було.

Код буває рівно таким самим. Зрозумілий код - це холодильник із підписами. Незрозумілий - ті самі двадцять контейнерів: «суп номер раз», «суп номер два», x, y, flag. І ось що прикро: незрозумілий код однаково мучить і тебе, і твого ШІ-агента.

Навіщо вайбкодеру зрозумілий код

Ти вайбкодер. Ти не пишеш код руками - ти замовляєш його в агента. І саме тому зрозумілість важлива вдвічі:

• захочеш щось змінити - ти (або агент) знайдете потрібне місце за секунди, а не за пів години;
• агент, читаючи зрозумілий код, витрачає менше токенів і рідше помиляється - йому не доводиться вгадувати, що за звір цей q;
• менше багів: половина поломок народжується з «ой, я думав, ця змінна про інше»;
• проєкт не перетворюється на болото за місяць, коли ти й сам забудеш, що взагалі писав.

Зрозумілий код - це подарунок майбутньому собі. А майбутній ти обовʼязково забуде, що таке tmp2 і навіщо тут число 86400. (Спойлер: це секунди в добі. Але дізнаєшся ти це за годину гуглення.)

Чотири правила чистого коду, яких дотримується Claude

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

1. Промовисті імена змінних і функцій

Імʼя змінної чи функції має пояснювати, що всередині. Без жодного коментаря.

2. DRY - не повторюй той самий код

DRY DRY (Don’t Repeat Yourself - «не повторюй себе») - принцип: той самий шматок логіки живе в одному місці. Потрібно у трьох місцях - винеси в спільну функцію й клич її. - це про копіпасту. Скопіював той самий шматок тричі? Вітаю: ти завів собі три місця, які тепер доведеться правити синхронно. Забув одне - отримав баг. І він, звісно, вистрелить у найнеслушніший момент.

Лікується на диво просто. Спільний шматок виносимо в одну функцію й кличемо її звідусіль. Змінив в одному місці - змінилося скрізь.

3. KISS - роби простіше, не ускладнюй

KISS KISS (Keep It Simple, Stupid - «роби простіше, друже») - принцип: бери найпростіше рішення, яке працює. Не ускладнюй заради майбутнього, яке може й не настати. - це про спокусу «зробити круто й на виріст». Не треба. Найпростіше рішення, яке працює, майже завжди бʼє «розумне». Зрозумілий код, що просто робить свою справу, завжди перемагає хитрий код, який треба розгадувати як ребус.

Поряд живе близький за духом YAGNI YAGNI (You Aren’t Gonna Need It - «тобі це не знадобиться») - не пиши код під гіпотетичне майбутнє. Знадобиться - додаси тоді. : не проси агента будувати функції, що «раптом знадобляться». Знадобляться - додаси, це пʼять хвилин. А ось тягнути зайвий код увесь цей час - дорого й марудно.

4. Магічні числа: ховаємо за іменами-константами

Магічне число Магічне число - число прямо в коді без пояснення, наприклад 3 чи 86400. Незрозуміло, що воно значить і чи можна його міняти. Лікується: даєш числу імʼя-константу. - це голе число посеред коду. Бачиш retryCount > 3 - а чому саме 3? А що рвоне, якщо поставити 5? Дай числу імʼя: MAX_RETRIES = 3. І сенс на місці, і міняти тепер в одному рядку.

Приклад із життя: кошик інтернет-магазину

Ти попросив агента: «зроби кошик для інтернет-магазину». За тиждень просиш: «додай знижку 10% для замовлень від 5000 гривень». І тут починається біль:

1. Агент написав розрахунок суми у трьох місцях - на сторінці товару, у кошику й під час оплати. Чиста копіпаста. Знижку треба вставити тричі, і в одному місці він, звісно, забуває.
2. У коді стирчить голе число 5000 без імені. Агент не впевнений: це поріг знижки, ліміт доставки чи ще щось.
3. Змінні звуть a, sum2, tmp. Агент палить токени, щоб зрозуміти, що де, і все одно плутається.

А тепер дивись, як попросити одразу по-людськи - щоб усього цього болю просто не сталося:

Зроби кошик для інтернет-магазину. Пиши зрозумілий код за простими правилами:


Давай змінним і функціям промовисті імена. Не x і tmp, а cartTotal, applyDiscount, isEligibleForDiscount. Функції - дієслово плюс про що.


Не дублюй логіку. Розрахунок підсумкової суми має жити в одній функції, яку кличуть звідусіль, а не копіюватися по сторінках.


Не зашивай голі числа в код. Поріг знижки й відсоток винеси в іменовані константи зверху, наприклад DISCOUNT_THRESHOLD і DISCOUNT_PERCENT, щоб їх легко було міняти в одному місці.


Роби максимально просто. Жодних заготовок на майбутнє, яких я не просив.

Після коду у двох словах поясни, де яка константа і де живе розрахунок суми.

Часті помилки вайбкодерів із кодом

• Погоджуватися на імена x, tmp, data2. Побачив такі в коді агента - попроси перейменувати по-людськи. Це безкоштовно й рятує години.
• Терпіти копіпасту. Той самий шматок у трьох місцях - проси винести в спільну функцію. Інакше правки розповзуться, і щось обовʼязково відвалиться.
• Лишати голі числа. Будь-яке «магічне» число попроси перетворити на іменовану константу зі зрозумілою назвою.
• Дозволяти «зробити на виріст». Зайві функції «раптом знадобляться» - це зайвий код, який треба читати й тягнути далі. Проси найпростіше, що розвʼязує задачу.
• Думати, що зрозумілість - це для програмістів. Усе навпаки: що зрозуміліший код, то рідше тобі, вайбкодеру, доведеться лізти в техніку, коли треба щось поправити.