Был ли налажен процесс оформления документации кода в ваших Flutter-проектах?

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

Вот смотри, как я обычно делаю, чтобы не было потом волнения ебать, когда кто-то новый в проект заходит и глаза по пять копеек делает.

Первое, основа основ — это комменты прямо в коде, но не абы какие. Я использую этот встроенный dartdoc, через три слеша ///. Это не просто так, чтобы от балды написать. Это чтобы потом можно было красивую бумажку нагенерить, и любой, кто зайдет, сразу видел, что к чему. Типа инструкция к микроволновке, а то без неё только разогреть, а тут и гриль, и конвекция, и таймер на три этажа.

/// Сервис для управления аутентификацией пользователя.
///
/// По сути, главный по таблеткам на входе. Отвечает за логин, логаут, обновление этого вашего токена,
/// который всем так нужен. Без [AuthRepository] — просто красивая коробочка, работать не будет.
class AuthService {
  final AuthRepository _repository;

  /// Создает экземпляр [AuthService]. Кидаешь ему репозиторий, а он тебе сервис.
  /// Как в автомат монетку.
  AuthService(this._repository);

  /// Основной метод — пускает пользователя внутрь.
  ///
  /// Скармливаешь ему [email] и [password], а он тебе выдает [AuthResult] — либо пропуск,
  /// либо пиздюлину в виде ошибки. Честно, без подвохов.
  ///
  /// **Вот, смотри, как этим пользоваться, чтобы не обосраться:**
  /// ```dart
  /// final result = await authService.login('user@mail.com', 'password123');
  /// if (result.isSuccess) {
  ///   print('Ура, токен: ${result.token}');
  /// } else {
  ///   print('Всё, пиши пропало: ${result.error}');
  /// }
  /// ```
  Future<AuthResult> login(String email, String password) async {
    // ... а тут внутри уже магия происходит
  }
}

Второе — README.md. Это лицо проекта, его паспорт. Если там пусто или написано «запусти и работает» — это пизда рулю и доверия ебать ноль. У меня там всегда:

• Коротко — о чём проект. Не роман, а два предложения.
• Чёткая инструкция: вот команда, вот файл с настройками, вот ссылка на Фигму, вот сюда переменные окружения пихать. Как будто для идиота пишу, который я сам через полгода.
• Список ключевых зависимостей — чтобы было понятно, на каких китах всё держится.

Третье — если архитектура сложная. Ну там Clean Architecture какая-нибудь или Feature-first. Это же ёперный театр, новичок зайдет и просто охуеет от папок. Поэтому я в docs/ могу накидать простенькую диаграмму, кто от кого зависит, или описать, как данные по конвейеру бегают. Чтобы не было потом вопросов «а этот блоб откуда здесь взялся?».

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

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