Многие говорят, что код должен быть самодокументируемым.
Так говорят только про случаи типа:
// Время до перегрева реактора в секундах
var a = 42;
return id % 3; // 3 - это количество наших серверов. Тут мы находим id нужного сервера, на котором хранятся данные
В вышеназванных случаях комментарий не нужен и может быть заменён нормальным неймингом.
В некоторых случаях комментарии можно заменить на нормальные типы.
// ПЛОХО!
/// <param name="time">Дата и в формате rfc2822</param>
public void DoSomething(string time) {}
// Хорошо!
public void DoSomething(DateTime time) {}
Писать комментарии в коде нужно там, где что-то не очевидно (описание какого-то алгоритма или протокола, например, ссылки на задачи, в рамках которых был добавлен какой-то неочевидный, но важный "костыль" и так далее)
+ Следует пользоваться встроенными средствами для документирования.
В тех проектах, где я работал документацию поддерживали по настроению. Многие важные аспекты не были описаны. Много было неактуальной информации. Если посмотреть в перспективе на такой подход, то чем сложнее будет становиться проект тем больше будет появляться пробелов в документации и тем больше будет неактуальных мест. По моему в больших масштабах такой подход вообще не приносит пользы.
Если вашей команде документация действительно важна, то её нужно вносить в основной цикл разработки.
Что-то типа
Specification -> Design review -> Development -> Review -> Testing -> Documentation -> Release
Тоесть нет документации - нет релиза. Нужно вносить роль технического писателя, который будет писать тексты и следить за актуальностью.
которые автоматически показывали бы покрытие кода документацией.
Код документацией покрывать не надо (по крайней мере так, как это обычно тестами происходит).
А вот для покрытия методов и публичного api и так есть инструменты для проверки. Например в C# даже warning есть
соответствующий.
что-то похожее на TDD - когда ты пишешь документацию а потом код
Ну так это и так должно быть в процессе разработки. Аналитик пишет спецификацию, ты, как разработчик, её дорабатываешь до уровня "это вот так лучше реализовать", потом по этой спецификации можно написать тесты и код.
PS: Попробуй отталкиваться от того, кто будет эту документацию читать.
1. Новые разработчики в твоей команде во время онбординга? Тогда проще C4 Diagram нарисовать
2. Другие разработчики, которые хотят с твоим сервисом интегрироваться? Тогда и описывай протокол взаимодействия, примеры приложений, и имеющиеся публичные методы
3. Техподдержка? Тогда лучше посмотреть в сторону базы знаний
4. Пользователи системы? Тогда лучше отталкиваться от вариантов использования - инструкции, как сделать то или иное действие, обзоры разных модулей.
5. Аналитик при продумывании новых фич? Тогда тут нужно что-то среднее между п1, п2, и п3.
6. Никто? Тогда и не мучай бумагу.
