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

Question

[angelzzz]

Есть большой проект, который долго разрабатывался одним человеком на js (coffescript + noda.js). Необходимо сделать документацию, чтобы с проектом могли работать другие разработчики. Где можно почитать какие есть принципы и подходы к написанию документацию? С чего начать, как вести?

Comments

[Одиночка Айс]

Комментарии уже не катят?

[angelzzz]

Одиночка Айс, спасибо! Ваш комментарий очень полезен

[Dark Hole]

coffescript + noda.js

Спасибо за настроение)

Answer 1

[kn0ckn0ck]

Есть две крайности, которых лучше избегать:
1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается

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

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

Кстати, проектная работа, это не только документация к коду, это еще и свод правил, которые позволят архитектуре не расползтись кто в лес кто по дрова, а также сохранят стилистику написания кода для единообразия и легкой поддерживаемости кода.

Comments

[Alex Wells]

Думаю, вышеописанные пукнты не вяжутся с JS, хоть и прекрасно работают в других средах (php, java etc).

На JS вообще очень сложно писать "правильно" и "хорошо"))

[Даниил Колесниченко]

Alex Wells, очень странное заявление, особенно учитывая что речь идёт о документации, а это к конкретному языку программирования прямого отношения не имеет. На JS точно также можно писать (по крайней мере, относительно) самодокументируемый код, писать JSDoc-комментарии и генерировать документацию из них, писать юнит-тесты.

[Alex Wells]

Даниил Колесниченко, ну, на JS очень сложно придерживаться этого, ибо возможности языка в класическом ООП очень скудные и написать хороший код, читаемый обычным человеком на JS - имхо очень сложно и нерентабельно.

Согласен, JSDOC, юнит тесты и автоматическая документация прекрасно работают в JS, но это, имхо, вообще не тот язык, который следует использовать в таких приложениях.

[Anton Filippov]

Alex Wells, вы сейчас пишите из 2007 года?

[Alex Wells]

flppv, я извиняюсь, если не совсем в теме, но я и писал бекенд на JS, и смотрел - нигде ничего хорошего не видел, видимо в этом моя проблема.

На счет 2007-го, а разве в JS уже появилась статическая типизация, интерфейсы, приватные свойства?))

[Anton Filippov]

Alex Wells, ага, появились :)

[Alex Wells]

flppv, если вы про TS - то это workaround, а не решение. К тому же даже он недотягивает до привычных ООП языков, как java, например.

Да и в сто раз проще написать hhvm совместимый код на PHP+фрейме ежели использовать его. Выйдет и быстрее, и проще, и лучше.

[Даниил Колесниченко]

Alex Wells, я вот типа ни разу не защитник JS, но ругать JS и приводить в пример PHP - такое.

[Alex Wells]

Даниил Колесниченко, а вы посмотрите на php 7.1+ и сравните производительность hhvm php и node) Вы удивитесь)

[Даниил Колесниченко]

Alex Wells, лол, какое отношение производительность имеет к хорошему, самодокументируемому и т.д. коду? Оба языка объективно очень плохо задизайнены изначально, из обоих теперь пытаются сделать что-то приличное, оба при этом остаются говноязыками по сути.

[Alex Wells]

Даниил Колесниченко, в PHP 7 есть все возможности из коробки, а в JS - нету даже с TS. В этом и разница.

А на счет хорошего кода - на PHP я встречал хороший код, да и сам стараюсь писать как можно лучше, и, имхо, на PHP написать таковой - проще. Знаю, что вы скажите, что это не от языка зависит - частично соглашусь, но это не совсем так, если мы говорим о задачах из реального мира, а не синтетике. Сравнить тот же веб:

- в js есть лидеры, вроде koa & express - и оба лишь http сервера, не фреймворки (как бы они там не называли себя). Ни один из них я бы не использовал. А что-то, что можно назвать фреймворком - висит где-то в npm с 10 тысячями скачиваний и сотней иссьюсов на гите. И это скорее проблема языка, ежели его комьюнити.
- в PHP же есть полноценные фреймворки, вроде laravel & symfony. Они диктуют, как и где писать код. Более того, сам язык позволяет использовать статическую типизацию из коробки и юзать ООП в разумных пределах (дженерики не завезли).

[Karpion]

kn0ckn0ck:

автоматическая документация (генерится из комментариев) - эффективно, только если сам код закрыт.

Зачем м.б. нужна документация к коду людям, которые не имеют доступа к собственно коду?