Красивый код на Python: понятные имена, типы, ошибки

Что значит «красивый код» простыми словами

Возьмём два рецепта борща. Первый: «налей воды, порежь и брось свёклу, потом капусту, посоли, вари 40 минут». Второй: «возьми X, сделай с ним Y, добавь Z, жди T». Оба, в теории, рабочие. Но по первому борщ сварит даже школьник. А по второму - только тот, кто его написал. И то через неделю сам забудет, что за зверь этот Z.

Код на Python - такой же рецепт, только для компьютера. И есть нюанс, о котором новички не догадываются: код читают чаще, чем пишут. Ты сам через месяц. Твой напарник. И - внимание - твой ИИ-агент, когда ты бросишь ему «почини баг». Красивый код они схватывают с первого взгляда. Уродливый расшифровывают по буквам, как заклинание из пыльной книги.

Зачем красивый код вайбкодеру, который сам не пишет

Логичный вопрос. Ты вайбкодер. Python по буквам за тебя набирает агент. Так какое тебе дело до «красивого кода»? А вот какое: планку качества задаёшь именно ты. Что попросишь - то и получишь. И вот что меняется, когда планка высокая:

• красивый код агент дополняет с первого захода, а в уродливом путается и ломает то, что рядом работало;
• понятные имена и типы = меньше багов, потому что и тебе, и агенту видно, что куда течёт;
• вернёшься к проекту через месяц - и сам разберёшься в своём коде, а не будешь умолять агента объяснить, что ты тут наворотил;
• одна фраза в промпте - «пиши питонично» - подтягивает весь проект почти бесплатно.

Разница между «агент собрал мне скрипт, и он работает» и «агент собрал мне скрипт, который я могу развивать» - это почти всегда разница в красоте кода. Поехали разбирать, из чего она складывается.

Из чего складывается красивый Python: четыре кита

В мире Python есть негласный закон - «Readability counts», читаемость превыше всего. Разберём по слоям: от простого к интересному.

Понятные имена переменных и функций вместо хитрых трюков

Правило номер один: код должен быть очевидным. Сравни две функции - делают они одно и то же, возвращают только активных пользователей.

Хорошо: get_active_users(users). Ты ведь даже не зная Python уже понял, что она делает? «Верни тех пользователей, у кого is_active». Имя само всё рассказало.

Плохо: g(u). А тут что? Что за g? Что за u? Что внутри - x.a? Загадка на загадке, сверху ещё одна загадка. Работает точно так же, но прочитать - без шансов.

Подсказки типов в Python: наклейки на коробках

В Python можно подписать, какой «груз» заезжает в функцию и что из неё выезжает. Называется это подсказки типов Подсказки типов (type hints) - пометки в коде о том, какого типа данные ожидаются: текст, число, список и так далее. Например, `name: str` значит «name - это строка». Программу они не меняют, но делают её понятнее людям, агенту и проверяющим инструментам. .

Смотри: запись def process_items(items: list[str]) -> dict[str, int] читается как «функция берёт список строк и отдаёт словарь, где ключи - строки, а значения - числа». Без этих пометок коробки едут без наклеек. И гадай потом сам, что там внутри.

Что с этого вайбкодеру? Агент по типам сразу видит, как устроены данные, и не путается. Бонусом: специальные инструменты-проверяльщики ловят ошибки ещё до того, как ты нажмёшь «запуск».

Обработка ошибок: лови конкретные, а не «всё подряд»

Что-то всегда может сломаться, и Python даёт это поймать. Но ловить можно по-разному - и между этими способами пропасть.

Плохо - поймать «всё подряд» и молча проглотить. Программа упала, а ты даже не в курсе. Это как заклеить скотчем лампочку «check engine»: мигать перестала, спорить не буду, а двигатель тем временем тихо умирает. Самый коварный баг - тот, который ты спрятал от самого себя.

Хорошо - поймать конкретную ошибку и честно сказать, что стряслось: «файл настроек не найден по такому-то пути». И всё. Ты видишь причину, агент видит причину, чините по делу, а не гадаете на кофейной гуще.

Питоничный стиль вместо «как в других языках»

У Python свой почерк - короткие читаемые конструкции, которые экономят строки и делают код яснее. Зубрить их наизусть не надо. Достаточно знать, что они есть, и просить агента ими пользоваться:

• f-строки для текста: значения вставляются прямо внутрь строки - красиво и без склейки плюсами.
• списочные включения (list comprehensions) для простых превращений: «возьми имена всех активных пользователей» - одна строка вместо цикла на пять.
• with для работы с файлами: открыл - и оно гарантированно закроется, даже если что-то рухнет по дороге. Помнить про закрытие руками не нужно.
• pathlib для путей к файлам - вместо ручной склейки строк через слэши.

Пример из жизни: рабочий, но уродливый код

Ты просишь агента: «напиши скрипт, который читает список ссылок из файла и скачивает каждую». Он бодро выдаёт рабочий код. Запускаешь - половина ссылок скачалась, половина нет, а почему - гробовая тишина: скрипт молча проглотил ошибки. Имена переменных - a, b, tmp. Проходит неделя, ты хочешь добавить «а ещё сохраняй размер файла» - и агент, спотыкаясь об этот код, крушит то, что только что работало.

В чём подвох? Код был рабочий, но уродливый. Без имён, без типов, с «голым except», который замёл все проблемы под ковёр.

А теперь смотри, как попросить с самого старта, чтобы получить красивый и развиваемый результат:

Напиши на Python скрипт, который читает список ссылок из файла и скачивает каждую. Пиши код красиво и питонично:

Давай функциям и переменным понятные имена - по названию должно быть ясно, что делает функция. Никаких имён в одну букву.
Проставь подсказки типов у всех функций: что входит и что выходит.
Ошибки лови конкретно (например, файл не найден или сеть упала) и печатай понятное сообщение, что именно пошло не так. Никакого «голого except», который молча всё проглатывает.
Используй питоничные приёмы: f-строки для текста, with для работы с файлами, pathlib для путей.
Следуй стандарту оформления PEP 8.
В конце коротко объясни простыми словами, что делает каждая функция.

Частые ошибки новичка в вайбкодинге

• Радоваться, что «работает», и не смотреть как. Рабочий, но уродливый код - это мина замедленного действия. Развивать его потом - чистое мучение.
• Не просить типы и имена. По умолчанию агент легко выдаст тебе g(u). Попросишь красиво - получишь красиво. Всё в твоих руках.
• Прятать ошибки. «Голый except» делает баги невидимыми. Всегда проси ловить конкретно и сообщать о проблеме.
• Гнаться за «умностью». В Python ценится не хитрый трюк в одну строку, а понятность. Ясность бьёт показуху.
• Не давать стандарт. Допиши в промпт «по PEP 8» - это общепринятый стандарт оформления Python, и агент сразу подтянет аккуратность.
• Растить функции-монстры. Функция делает десять дел сразу? Её тяжело читать и тебе, и агенту. Проси резать на маленькие, с понятными именами.