Ответ
Да, регулярно пишу техническую документацию разных уровней:
-
Кодовая документация (XML-комментарии): Обязательна для публичных API. Позволяет генерировать справочную документацию через инструменты вроде DocFX или Sandcastle, а также отображает подсказки в IDE.
/// <summary> /// Вычисляет площадь круга по заданному радиусу. /// </summary> /// <param name="radius">Радиус круга. Должен быть положительным числом.</param> /// <returns>Площадь круга.</returns> /// <exception cref="ArgumentOutOfRangeException">Выбрасывается, если <paramref name="radius"/> меньше или равен нулю.</exception> public double CalculateCircleArea(double radius) { if (radius <= 0) throw new ArgumentOutOfRangeException(nameof(radius), "Radius must be positive."); return Math.PI * radius * radius; } -
Документация API (OpenAPI/Swagger): Настраиваю автоматическую генерацию спецификации из аннотаций контроллеров, добавляю описания и примеры.
-
Проектная документация (README.md, wiki): Пишу
README.mdдля репозитория, который включает:- Цель проекта и его краткое описание.
- Инструкции по сборке и запуску (требуемые SDK, команды
dotnet, переменные окружения). - Описание архитектуры и ключевых компонентов.
- Примеры использования API (cURL, Postman).
- Руководство по внесению вклада (contribution guidelines).
Хорошая документация снижает порог входа для новых разработчиков, упрощает поддержку и является частью профессионального качества кода.
Ответ 18+ 🔞
А, документация, говоришь? Ну, это как тот самый Герасим с метлой — вроде бы и не главный герой, но без него двор быстро превращается в помойку, блядь.
Да, пишу регулярно, иначе потом сам же и расхлёбываю. Вот смотри, как я это делю:
-
Эти вот XML-комментарии к коду. Это как инструкция к микроволновке прямо на её кнопках. Без них другой разработчик, чтобы разогреть суп, будет жать на все кнопки подряд, пока не случится пиздец. Обязательно пишу для всего, что торчит наружу из класса — для публичных методов, свойств. Потом из этой хуйни автоматом генерируется нормальная справка, да и в Visual Studio при наведении курсора всё красиво всплывает. Смотри, как это выглядит:
/// <summary> /// Считает площадь круга. Ну, круга, Карл, что тут непонятного? /// </summary> /// <param name="radius">Радиус, ёпта. Ноль или отрицательный — не предлагать.</param> /// <returns>Площадь, блядь. Число.</returns> /// <exception cref="ArgumentOutOfRangeException">Вылетит, если какой-то умник попробует передать хуйню вместо радиуса.</exception> public double CalculateCircleArea(double radius) { if (radius <= 0) throw new ArgumentOutOfRangeException(nameof(radius), "Ну ты чего, как так-то? Радиус должен быть больше нуля!"); return Math.PI * radius * radius; } -
Документация для API (этот ваш Swagger/OpenAPI). Тут вообще магия, блядь. Навешал специальных атрибутов на контроллеры — и готово, у тебя целый интерактивный справочник, где можно тыкать кнопочки и смотреть, что API отдаёт. Главное — не полениться и примеры нормальные запросов-ответов написать, а то будет просто автогенерированная пустышка, от которой пользы — как от козла молока.
-
А это, блядь, самое главное — README.md в корне проекта. Это как вывеска на магазине. Если там хуйня написана или вообще пусто, то внутрь никто и не зайдёт. Я туда впихиваю всё:
- Что это за зверь? Двумя предложениями, чтобы даже менеджер понял.
- Как это запустить, чтобы не взорвалось? Конкретные команды:
dotnet restore,dotnet run, какие переменные окружения в.envфайлик запихнуть. Без этого каждый новый чувак будет неделю гуглить, как завести этот движок. - Из чего это собрано? Пару слов об архитектуре — что за чем стоит, чтобы не пришлось полдня разгребать код лопатой.
- Как с этим работать? Примеры вызовов API — готовые curl-команды или скриншот из Postman'а. Идеально, когда можно просто скопировать, вставить в терминал и увидеть результат.
- Хочу помочь! Небольшой гайд для контрибьюторов — как оформить пул-реквест, какие стандарты кода соблюдать.
Короче, хорошая документация — это не занудство, а проявление уважения, блядь. Уважения к своему же времени в будущем и к коллегам, которые не хотят тратить полдня на расшифровку твоего гениального, но немого кода. Без неё проект превращается в ту самую избушку на курьих ножках: снаружи вроде стоит, а зайди внутрь — одни потроха и непонятно, где тут печка, а где смерть Кощея спрятана.