Ni55aN
@Ni55aN

Как вы документируете свой JS код?

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

В первом случае можно ориентироваться по туториалу к библиотеке (если есть вопросы по предметной области), в остальном все и так должно быть ясно хотя бы для тех, кто умеет читать код.
Во втором уже посложнее. Нужно как-то отдельно комментировать код, чтобы не перенасыщать его лишним текстом, и как уже было сказано - могут быть не только текстовые описания. И писать это рядом с основной документацией к проекту не то, так как это будет больше полезно для contributor'ов, а не пользователей.

Есть ли какие-то инструменты для написания комментариев к коду отдельно от него, но с проверкой целостности? Чтобы подсказывало что нового появилось в коде и предлагало его прокомментировать, и контролировало изменения

P.S. Если кто-то хочет возразить по поводу самодокументируемого кода, то вот обратный пример
Особенно интересна строка:
var Tag = function(id, description, min, max, plc) {

Какой смысл тратить время на написание подобных комментов? Разве что тип указать, но в моем случае для этого есть transform-flow-strip-typesдля Babel

@param {String} id - The ID of the Tag.

Трата времени, если и так ясно из кода что первый параметр это идентификатор для создания метки
  • Вопрос задан
  • 299 просмотров
Пригласить эксперта
Ответы на вопрос 1
@AnneSmith
самая ленивая
генерирую список всех объектов по их id и соответствующего им функционала, очень удобно для отладки, сразу виден список объектов функционала, которые могли бы стать причиной ошибки

в комментариях пишу детали, которые сама со временем могу забыть, типа почему требуется делать именно так, а не иначе и референс на другую часть кода, которая имеет отношение к этой логике

или описываю суть функционала, если по названию метода нельзя однозначно его понять
Ответ написан
Комментировать
Ваш ответ на вопрос

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

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