Технические команды часто избегают лишней документации, но информация всё равно каким-то образом передаётся, сохраняется и развивается. В этой статье — попытка разобрать скрытые механизмы общения внутри инженерных команд: как выстраиваются негласные соглашения, каким образом рождаются "внутренние диалекты" и зачем вообще всё это, если есть JIRA, Confluence и куча других инструментов. Много примеров, блоков кода на разных языках и немного личного опыта.

Иногда кажется, что инженеры — это люди, которые могут передать целую архитектуру системы, не сказав ни слова. В одной комнате кто-то бросает "мы можем сделать это как в модуле расчётов", и другой человек кивает, зная, что это означает геттеры на Redis, обёрнутые в Python-классы с трёхуровневым кэшированием. Ни документации, ни схем, ни диаграмм. Только намёки, полунамеки и годами отточенные ассоциации.

Это не баг. Это — фича. И иногда, черт возьми, она работает куда надёжнее любой документации, которая всё равно устареет через два спринта. Эта статья — не про то, как всё надо делать по учебнику. Она про то, как на самом деле строится коммуникация в инженерной среде, где все всё понимают, но никто ничего не фиксирует.

Внутренний диалект: соглашения без слов

Каждая команда рано или поздно начинает говорить на своём языке. Даже не на сленге, а именно на техническом диалекте, который возникает из архитектурных решений, багов, антипаттернов и фреймворков, которые они выбрали (или, чаще, с которыми пришлось смириться).

Типичный пример — внутренние названия паттернов. Один проект называл "чебурашкой" сложный двухступенчатый пайплайн с fallback'ами, потому что он был кривой, но работал. Никто не писал об этом в вики, но достаточно было сказать "не забудь сделать чебурашку для этого запроса" — и всё было понятно.

Это работает до тех пор, пока новый разработчик не влетает в проект и не смотрит на вас как на безумных. Или пока один из вас не уходит, забирая с собой полсловаря.

Когда код говорит громче документации

На некоторых проектах код — это и есть единственная форма документации. Это особенно ярко проявляется в модулях, где нет ни одного README, но по структуре импортов, по названиям классов и по способу обработки ошибок можно понять, как всё работает.

# Язык: Python 3.10+
from fastapi import APIRouter, HTTPException

router = APIRouter()

@router.get("/balance")
def get_balance(user_id: int):
    if user_id not in user_storage:
        raise HTTPException(status_code=404, detail="User not found")

    balance = redis_cache.get(user_id)
    if balance is None:
        balance = fetch_from_db(user_id)
        redis_cache.set(user_id, balance)
    return {"balance": balance}

В этом коде нет явной документации, но тут есть паттерн: Redis как первый уровень, fallback в БД. Так работают почти все ручки в этом микросервисе. И это становится договорённостью, которую никто не оформляет — просто так принято.

Архитектура через git blame

Иногда самый эффективный способ понять архитектуру — это пройтись по git blame. Особенно в монолитах. Ты видишь, кто писал, в каком контексте, и какие комментарии оставлял. Вот пример характерного участка:

// Язык: Go
func (s *Service) ProcessEvent(ctx context.Context, e Event) error {
    switch e.Type {
    case TypeAlpha:
        return s.handleAlpha(ctx, e)
    case TypeBeta:
        return s.handleBeta(ctx, e)
    default:
        logger.Warn("Unknown event type", zap.String("type", e.Type))
        return nil
    }
}

Комментариев нет, но по коду ясно: здесь расширяемая обработка событий, типичная точка роста. У нас даже был мем: "Если не знаешь, где у нас проблема — ищи switch по типу и иди вниз".

Блоки с консольной логикой как форма коммуникации

Один из негласных способов передачи логики — через утилиты, которые никто не чистит. Вот пример shell-скрипта, который в нашей команде использовался как способ понять, как вообще деплоится сервис (и, честно говоря, был единственным местом, где всё было по шагам).

# Язык: Bash
#!/bin/bash

set -e

echo "Building Docker image..."
docker build -t my-service .

echo "Pushing image to registry..."
docker push my-service

echo "Applying Kubernetes manifest..."
kubectl apply -f k8s/deployment.yaml

echo "Deployment complete."

Вся команда понимала: если не знаешь, что делать — читай этот скрипт. Хоть он и не обновлялся года два, но всё ещё отражал основную идею пайплайна.

Архитектурная логика в шаблонах фронтенда

Во фронте, особенно в React-проектах, коммуникация идёт через шаблоны. Не UI-компоненты, а именно файловую структуру и подход к стейту.

// Язык: TypeScript (React)
import { useEffect, useState } from "react";
import { fetchProfile } from "@/api/user";

export function ProfileCard({ userId }: { userId: string }) {
  const [profile, setProfile] = useState(null);

  useEffect(() => {
    fetchProfile(userId).then(setProfile);
  }, [userId]);

  if (!profile) return <div>Loading...</div>;

  return (
    <div>
      <h2>{profile.name}</h2>
      <p>{profile.bio}</p>
    </div>
  );
}

Все знали: сначала идет загрузка, потом useEffect, потом null check, потом рендер. Не писано нигде, но нарушишь — тебя поправят. Или просто твой PR не примут.

«Шаблонная» логика в SQL — как форма архитектурного соглашения

Ещё один пример — SQL-запросы, которые выглядят как формальные шаблоны, но по сути передают архитектурные договорённости (например, как собираются отчёты).

-- Язык: SQL
SELECT
  users.id,
  users.name,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_revenue
FROM users
LEFT JOIN orders ON users.id = orders.user_id
WHERE users.created_at > NOW() - INTERVAL '1 year'
GROUP BY users.id, users.name
ORDER BY total_revenue DESC
LIMIT 100;

Когда кто-то писал отчёт — он начинал с этого шаблона. Остальное додумывалось. Это и был "язык" аналитиков внутри команды.

Ментальные модели: документация в голове

Если вы спросите разработчика в опытной команде: "а где у вас описано, как работает пайплайн доставки данных?" — он, скорее всего, сначала зависнет, потом скажет "ну, это в Airflow, а дальше сам поймёшь". Потому что документация живёт не в Notion, а в головах. А точнее — в ментальных моделях.

Ментальная модель — это способ интерпретировать текущую систему. Она включает в себя:

• Понимание не только того, что работает, но и почему именно так

• Историю багов, обходных путей и временных решений

• Контекст архитектурных компромиссов

Зачем всё это и что с этим делать

С одной стороны, хочется крикнуть: "пишите документацию! думайте о будущем!". Но реальность такая, что инженерия — это живая вещь, и пытаться задокументировать всё — всё равно что написать инструкцию к джем-сейшену.

Но есть компромисс:

• Делать архитектурные ревью с обсуждением решений (и записывать хотя бы итоги)

• Поддерживать readable code как форму коммуникации

• Заводить "инженерные байки" в внутренних чатах — это как устная документация

• Делать минимальные README по модулям с самыми спорными решениями

Вывод

Инженеры всё равно общаются. Даже если они молчат. Их язык — это структура кода, паттерны, архитектура и те самые "чебурашки". Понимание этого — шаг к построению сильных команд, где документация — не панацея, а инструмент. Один из многих.

Иногда молчание — золото. Особенно если оно написано в чистом Python, Go, Bash, React или SQL.