Как сделать документацию к коду?

Есть большой проект, который долго разрабатывался одним человеком на js (coffescript + noda.js). Необходимо сделать документацию, чтобы с проектом могли работать другие разработчики. Где можно почитать какие есть принципы и подходы к написанию документацию? С чего начать, как вести?
  • Вопрос задан
  • 7418 просмотров
Решения вопроса 1
@kn0ckn0ck
Продюсер
Есть две крайности, которых лучше избегать:
1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается

Стандартные решения:
1. самодокументируемый код, составленный так, что читающий может понять что для чего и в какой последовательности работает.
2. описание интерфейсов (назначение метода, тип/суть параметров и т.п.) в форме комментов в коде.
3. автоматическая документация (генерится из комментариев) - эффективно, только если сам код закрыт.
4. модульные тесты, фиксирующие требования к коду и демонстрирующие его использование.
5. описание высокоуровневого дизайна (High Level Design, HLD), описывающий какие элементы существуют, их взаимосвязь друг с другом и основные сценарии взаимодействия.

Работающая документация - это компромисс из этих практик, релевантный конкретной ситуации.

Кстати, проектная работа, это не только документация к коду, это еще и свод правил, которые позволят архитектуре не расползтись кто в лес кто по дрова, а также сохранят стилистику написания кода для единообразия и легкой поддерживаемости кода.
Ответ написан
Пригласить эксперта
Ответы на вопрос 1
guar
@guar
https://t.me/another_way_out
Выше идеальный ответ, добавлю еще неплохую ссылку www.writethedocs.org/guide
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы