Гарний код на 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, і агент одразу підтягне акуратність.
• Вирощувати функції-монстри. Функція робить десять справ одразу? Її важко читати і тобі, і агенту. Проси різати на маленькі, зі зрозумілими іменами.