ShadowCrow

Глава 1: Отговорка «Это и так понятно»

Есть особый тип программиста, который смотрит в экран, наблюдает, как строки загадочного кода бегут по терминалу, и думает: «Это искусство». Для него каждый цикл `for`, каждое условие `if`, каждая тщательно названная переменная вроде `data2` или `tempFinal_v4` несёт настолько глубокий, настолько интуитивно понятный смысл, что объяснение только разрушило бы всю магию.

«Это и так понятно», — заявляют они, пренебрежительно махнув рукой, когда их спрашивают, почему API возвращает ошибку 418 вместо ожидаемых данных. — «Просто прочитай код».

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

Но давайте будем справедливы. Отговорка «Это и так понятно» рождается не из лени. Нет, это философия, глубоко укоренившаяся вера в то, что:

Хороший код не нуждается в объяснениях. Чем меньше комментариев, тем умнее он выглядит. Чистый, недокументированный репозиторий — это знак отличия.

Документация — для слабых. Настоящие программисты идут по жизни через отладку. Если тебе нужен проводник, чтобы пробраться через эти джунгли спагетти-логики, возможно, ты просто не создан для этой работы.

Если я могу это понять, значит, и ты сможешь. Потому что, очевидно, у всех остальных такой же опыт, образ мышления и уровень потребления кофеина, как у человека, написавшего этот код.

В духе товарищества давайте рассмотрим несколько реальных сценариев, где эта отговорка сияет во всей красе.

Пример: Гений одной строки

В особенно амбициозный момент Алекс написал одну строку кода на Python, которая делает что-то чудесное. Когда его спрашивают, что именно, он пожимает плечами и говорит: «Это же однострочник. Просто прочитай».

Что она делает? Кто знает. Нет ни комментария, ни README, только это загадочное заклинание. Будущие поколения разработчиков будут изучать эту строку как древние иероглифы, пытаясь разгадать её назначение.

Пример: «Модульная загадка»

Архитектура микросервисов Софии — чудо современной инженерии. Каждый сервис идеально модульный, со своим репозиторием, скриптом развёртывания и, естественно, нулём документации.

«Там всё и так понятно», — уверяет София команду на встрече. — «Сервис A общается с сервисом B, тот вызывает сервис C. Это просто HTTP-запросы».

Чего она не упоминает, так это того, что у сервиса B есть скрытая зависимость от legacy-системы, написанной на COBOL, а сервис C требует конкретную версию Java, которую последний раз видели в 2008 году.

Почему мы любим эту отговорку

В своей основе отговорка «Это и так понятно» — это акт веры. Это вера в силу человеческого разума расшифровать что угодно при достаточном количестве времени, кофе и отчаяния. Это ещё и негласный вызов — перчатка, брошенная к ногам любого, кто достаточно смел, чтобы спросить: «А что это делает?»

Потому что, в самом деле, где веселье в том, чтобы просто знать, что должен делать код?

Совет для начинающих

Если вы новичок в искусстве не документировать свой код, вот совет: чем более запутан ваш код, тем увереннее вы должны звучать, называя его «самоочевидным». Бонусные очки, если при описании вы используете слова вроде «элегантный», «прямолинейный» или «очевидный».

Помните: документация временна. Путаница вечна.

Глава 2: «Код всё ещё меняется, так зачем напрягаться?»

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

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

Жизненный цикл недокументированного кода

Давайте посмотрим, как эта отговорка проявляется в реальной жизни.

День 1: Свежий старт

Команда начинает блестящий новый проект. Настроение отличное. Обсуждают чистую архитектуру, надёжное тестирование и — осмелимся сказать? — документацию. Но кто-то подаёт голос:

«Давайте подождём, пока MVP будет готов. Нет смысла документировать то, что может измениться».

День 30: Фаза MVP

MVP доставлен, но теперь нет времени писать документацию, потому что у клиента срочные запросы на новые функции.

«Давайте подождём до следующего спринта. Тогда всё подчистим и задокументируем».

День 365: Забытые джунгли

Проект прошёл через 47 спринтов, три разворота стратегии и частичную перепись. Никто не помнит, как работал исходный код, а единственный человек, который помнил, ушёл в другую компанию. Документация? Какая документация?

«Теперь уже слишком поздно. Нам пришлось бы переписать всё целиком, чтобы просто понять, как это работает».

Философия, стоящая за отговоркой

Гениальность отговорки «Код всё ещё меняется» заключается в её циклической логике:

- Вы не документируете код, потому что он меняется.

- Код продолжает меняться, потому что его никто не понимает.

- Никто его не понимает, потому что нет документации.

Это самоподдерживающаяся экосистема путаницы, и все участники либо учатся принимать её, либо страдают.

Но давайте не упустим более глубокие истины, которые эта отговорка раскрывает о процессе разработки ПО:

Изменения постоянны. В мире agile-методологий изменения приветствуются. Если кодовая база не находится в постоянном движении, вы вообще инновациями занимаетесь?

Документация — движущаяся цель. Зачем тратить время на документирование чего-то, что через две недели может вообще не существовать? Лучше подождать, пока всё «устаканится» — спойлер: этого никогда не случится.

Будущие разработчики — экстрасенсы. Несомненно, люди, которые унаследуют этот код, интуитивно поймут его назначение. В конце концов, разве не для этого существуют инструменты отладки?

Реальные последствия

Конечно, у этой отговорки есть и минусы — сущие мелочи, правда. Например:

Адаптация новых разработчиков: «Просто погрузись в кодовую базу. Там всё довольно прямолинейно, когда разберёшься с 17 недокументированными соглашениями, которые мы используем».

Отладка в продакшене: «Эта проблема возникает только по четвергам, когда сервер базы данных под нагрузкой. Ах да, логика этой функции размазана по пяти микросервисам. Удачи!»

Поддержка legacy-систем: «Мы написали этот код пять лет назад, когда экспериментировали с функциональным программированием. Нет, мы его не документировали. А почему ты спрашиваешь?»

Практический пример бессмысленности

Познакомьтесь с Кевином. Кевин — младший разработчик, который только что присоединился к команде. Его первая задача — исправить баг в ключевой функции приложения. Вооружившись энтузиазмом и поиском в Google, Кевин погружается в работу.

Код представляет собой лабиринт вложенных функций, магических чисел и загадочных имён переменных вроде `x` и `z1`. Нет комментариев, нет README, нет дизайн-документов. Когда Кевин просит помощи, команда пожимает плечами:

«Эта часть кода всё ещё меняется. Просто разберись».

Три недели спустя Кевин переписал всю функцию с нуля. Она работает идеально, но он её не документирует. Почему?

«Код всё ещё меняется. Зачем напрягаться?»

И так цикл продолжается.

Как разорвать цикл

Отговорка «код всё ещё меняется» процветает там, где нет ответственности. Чтобы выбраться из неё, командам нужно принять радикальную идею: документации не обязательно быть идеальной, чтобы быть полезной.

Вот несколько практических советов по документированию кода, который находится в движении:

Пишите по ходу дела. Документируйте причины решений — «почему», даже если «что» ещё может измениться.

Делайте это легко. Сосредоточьтесь на высокоуровневых обзорах и ключевых концепциях. Мелкие детали оставьте на потом.

Используйте инструменты. Markdown-файлы, вики или даже комментарии в коде могут кардинально изменить ситуацию.

Помните: несовершенная документация лучше, чем её отсутствие. Наполовину готовая карта всё равно полезнее, чем слепое блуждание в темноте.

Совет для мастеров отговорок

Если вы по-настоящему преданы этой отговорке, вот как её продать:

Используйте модные слова вроде «итеративный», «agile» и «динамичный», чтобы объяснить, почему документация не нужна.

Намекайте, что написание документации замедлит прогресс, хотя именно её отсутствие вызывает бесконечные задержки.

Отмечайте, что никто другой тоже не документирует свой код, так почему вы должны?

Если всё сделать правильно, вы купите себе как минимум ещё шесть месяцев блаженного хаоса.

Ну такой вот примерно рецепт усредненный, потому что вариаций масса.

Берется обычное задание: сделать CI/CD-пайплайн, чтобы по тегу в гите собирался образ, пушился куда надо и деплоился в кубер. Делать просто — это не про моего чувака.

Он берет эту лабу, вываливает ее на инфраструктурную сковороду и начинает жарить. Сначала хуярит Nexus, потому что без собственного артефактного репозитория, видимо, даже hello-world не собирается. Потом сверху накидывает Jenkins, но не один, а три ноды, чтобы пайплайну было не скучно. Потом добавляет Kubernetes, тоже три ноды, потому что один кластер — это для слабых.

Дальше идет Ansible provision, чтобы всё это говно сначала само встало, потом само сломалось, потом само же пыталось себя починить. Для вязкости добавляется ArgoCD, чтобы деплой был не просто деплоем, а философским актом GitOps. Сверху щедро намазывается Keycloak, потому что без SSO и realm’ов лаба, конечно, не имеет права на существование.

Все это жарится до дыма, пока вентиляторы на ноуте не начинают звучать как взлетающий МиГ. В консоли одновременно горят Jenkins agents, kubelet’ы, ingress’ы, какие-то токены протухли, сертификаты не те, Argo орет красным, Nexus жрет диск, Keycloak задумался о смысле жизни.

Потом чувак откидывается на спинку кресла, смотрит на это чудовище и полушепотом приговаривает:

ух ля, фул фарш.

Любезно иногда предлагает посмотреть архитектуру, но я отказываюсь. Потому что стоит открыть его README, и оттуда начинает дуть enterprise-архитектурой, отпуском и нерешенными детскими травмами от недоделанных курсачей.

Chapter 1: The "It’s Self-Explanatory" Excuse

There’s a special kind of programmer who stares at their screen, watches lines of cryptic code cascade down the terminal, and thinks, “This is art.” To them, every for loop, every if statement, every carefully named variable like data2 or tempFinal_v4 carries a meaning so profound, so intuitive, that explaining it would somehow ruin the mystery.

“It’s self-explanatory,” they declare, waving their hand dismissively when asked why the API returns a 418 error instead of the expected data. “Just read the code.”

The irony, of course, is that “self-explanatory” is the tech equivalent of leaving a cryptic note in a bottle and expecting someone else to decode it decades later. It’s shorthand for “I didn’t feel like writing anything down.” Why waste time on documentation when you can make future developers—or yourself in six months—play a fun little game called “Guess What I Meant”?

But let’s be fair. The “It’s Self-Explanatory” Excuse isn’t born out of laziness. No, it’s a philosophy, a deeply held belief that:

1. Good code doesn’t need explanations. The fewer comments, the smarter it looks. A clean, undocumented repository is a badge of honor.

2. Documentation is for the weak. Real programmers debug their way through life. If you need a guide to navigate this jungle of spaghetti logic, maybe you’re just not cut out for this job.

3. If I can understand it, so can you. Because obviously, everyone else has the same background, thought process, and caffeine intake as the person who wrote the code.

In the spirit of camaraderie, let’s explore a few real-world scenarios where this excuse shines:

Case Study: The One-Liner Genius

In a particularly ambitious moment, Alex wrote a single line of Python code that does something miraculous. When asked about it, they shrug and say, “It’s a one-liner. Just read it.”

result = [x[::-1].capitalize() for x in open("data.txt").readlines() if x.strip()]

What does it do? Who knows. There’s no comment, no README, just this mysterious incantation. Future generations of developers will study this line like ancient hieroglyphics, trying to divine its purpose.

Case Study: The “Modular Mystery”

Sophia’s microservices architecture is a marvel of modern engineering. Every service is perfectly modular, with its own repository, deployment script, and, naturally, zero documentation.

“It’s all self-explanatory,” Sophia assures the team during a meeting. “Service A talks to Service B, which calls Service C. It’s just HTTP requests.”

What she doesn’t mention is that Service B has a hidden dependency on a legacy system written in COBOL, and Service C requires a specific version of Java last seen in 2008.

Why We Love This Excuse

At its core, the “It’s Self-Explanatory” Excuse is an act of faith. It’s a belief in the power of the human mind to decipher anything, given enough time, coffee, and despair. It’s also an unspoken challenge—a gauntlet thrown at the feet of anyone brave enough to ask, “What does this do?”

Because, really, where’s the fun in just knowing what the code is supposed to do?

Pro Tip for Beginners

If you’re new to the art of not documenting your code, here’s a tip: the more confusing your code is, the more confident you should sound when you call it “self-explanatory.” Bonus points if you use phrases like “elegant,” “straightforward,” or “obvious” while describing it.

Remember, documentation is temporary. Confusion is forever.

Chapter 2: “The Code Is Still Changing, So Why Bother?”

If there’s one thing software developers love more than writing code, it’s rewriting it. Codebases evolve at a breakneck pace, morphing from simple scripts into sprawling monstrosities of interconnected logic. And in the chaos of constant change, one excuse reigns supreme: “Why document it now? It’s just going to change tomorrow.”

This excuse is a masterstroke of deflection. It shifts the responsibility of documentation to some mythical point in the future—when the code is “done.” But here’s the kicker: code is never done. It lives, breathes, and grows like an out-of-control houseplant. And as it grows, so does the mountain of undocumented features, hacks, and workarounds.

The Lifecycle of Undocumented Code

Let’s take a look at how this excuse plays out in real life:

1. Day 1: The Fresh Start The team embarks on a shiny new project. Spirits are high. There’s talk of clean architecture, robust testing, and—dare we say it?—documentation. But someone pipes up:
   “Let’s wait until the MVP is ready. No point in documenting things that might change.”

2. Day 30: The MVP Phase The MVP is delivered, but now there’s no time to write documentation because the client has urgent feature requests.
   “Let’s wait until the next sprint. We’ll clean everything up and document it then.”

3. Day 365: The Forgotten Jungle The project has gone through 47 sprints, three pivots, and a partial rewrite. No one remembers how the original code worked, and the one person who did has left for another company. Documentation? What documentation?
   “It’s too late now. We’d have to rewrite the whole thing just to understand it.”

The Philosophy Behind the Excuse

The genius of “The Code Is Still Changing” excuse lies in its circular logic:

• You don’t document the code because it’s changing.

• The code keeps changing because no one understands it.

• No one understands it because there’s no documentation.

It’s a self-sustaining ecosystem of confusion, and everyone involved learns to embrace it—or suffer.

But let’s not overlook the deeper truths this excuse reveals about the software development process:

1. Change Is Constant: In the world of agile methodologies, change is celebrated. If the codebase isn’t in flux, are you even innovating?

2. Documentation Is a Moving Target: Why waste time documenting something that might not even exist in two weeks? Better to wait until things “settle down” (spoiler: they never do).

3. Future Developers Are Psychic: Surely, the people who inherit this code will intuitively understand its purpose. After all, isn’t that what debugging tools are for?

The Real Consequences

Of course, this excuse has its downsides—minor inconveniences, really. For example:

• Onboarding New Developers: “Just dive into the codebase. It’s all pretty straightforward once you figure out the 17 undocumented conventions we’re using.”

• Debugging in Production: “This issue only happens on Thursdays when the database server is under load. Oh, and the logic for that feature is spread across five microservices. Good luck!”

• Maintaining Legacy Systems: “We wrote this code five years ago when we were experimenting with functional programming. No, we didn’t document it. Why do you ask?”

A Case Study in Futility

Meet Kevin. Kevin is a junior developer who just joined the team. His first task is to fix a bug in a core feature of the application. Armed with enthusiasm and Google searches, Kevin dives in.

The code is a labyrinth of nested functions, magic numbers, and cryptic variable names like x and z1. There are no comments, no README, and no design docs. When Kevin asks for help, the team responds with a shrug:
“That part of the code is still changing. Just figure it out.”

Three weeks later, Kevin has rewritten the entire feature from scratch. It works perfectly, but he doesn’t document it. Why?
“The code is still changing. Why bother?”

And so the cycle continues.

Breaking the Cycle

The “Code Is Still Changing” excuse thrives on a lack of accountability. To break free, teams need to embrace a radical idea: documentation doesn’t have to be perfect to be useful.

Here are some practical tips for documenting code in flux:

1. Write as You Go: Document the “why” behind decisions, even if the “what” might change.

2. Keep It Lightweight: Focus on high-level overviews and key concepts. Save the nitty-gritty details for later.

3. Use Tools: Markdown files, wikis, or even comments in the code can make a world of difference.

Remember, imperfect documentation is better than none. A half-finished map is still more useful than wandering blindly in the dark.

Pro Tip for Masters of Excuses

If you’re truly committed to this excuse, here’s how to sell it:

• Use buzzwords like “iterative,” “agile,” and “dynamic” to explain why documentation is unnecessary.

• Suggest that writing documentation would slow down progress, even though the lack of it is causing endless delays.

• Point out that no one else is documenting their code either, so why should you?

Done correctly, you’ll buy yourself at least six more months of blissful chaos.

Stay tuned for Chapter 3: Chapter 3: “It’s Too Obvious to Write Down.”