Понятный код для вайбкодера: имена, 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. Увидел такие в коде агента - попроси переименовать по-человечески. Это бесплатно и спасает часы.
• Терпеть копипасту. Один и тот же кусок в трёх местах - проси вынести в общую функцию. Иначе правки разъедутся, и что-нибудь обязательно отвалится.
• Оставлять голые числа. Любое «магическое» число попроси превратить в именованную константу с понятным названием.
• Разрешать «сделать на вырост». Лишние функции «вдруг пригодятся» - это лишний код, который надо читать и тащить дальше. Проси самое простое, что решает задачу.
• Думать, что понятность - это для программистов. Всё наоборот: чем понятнее код, тем реже тебе, вайбкодеру, придётся лезть в технику, когда надо что-то поправить.