Как ссылаться на конкретные области кода в документации?

9

Я собираюсь покинуть проект, и прежде чем я уйду, мой начальник попросил меня документировать код (я не очень хорошо задокументировал). Это не имеет большого значения, проект не очень сложный. Но я нахожу в своей документации места, где я хотел бы сказать: «В строке XYZ обратите внимание, что происходит то-то и то-то».

В этом случае не имеет смысла ссылаться на конкретный номер строки, так как добавление или удаление одной строки кода немедленно устареет в документации. Есть ли лучшая практика для ссылки на конкретную строку кода без ссылки на нее по номеру строки?

Я рассмотрел засорение кода комментариями вроде:

/* linetag 38FECD4F */

Где «38FECD4F» - это уникальный тег для этой конкретной строки. Затем я могу добавить в документацию: «В строке с тегом« 38FECD4F »обратите внимание, что происходит то-то и то-то».

Есть еще идеи? Я чувствую, что, как правило, лучше документировать единицы кода в целом, а не отдельные их части, но в случае этого конкретного проекта есть ДЛИТЕЛЬНЫЕ ряды процедурного кода, которые никогда не реорганизовывались в более мелкие единицы.

loneboat
источник
Вы ссылаетесь на определенные местоположения из включающих методов или из комментариев к началу файла? В последнем случае вы можете использовать стиль "#" JavaDoc.
Арина
Я обычно ссылался на файл и метод («Уведомление в файле ABC в методе XYZ, происходит то-то и то-то»), но мне любопытно посмотреть, какие ответы приходят.
Майкл Ицоэ,
7
Не было бы более целесообразно в этих случаях просто поместить комментарии в реальный код?
Роберт Харви
есть ли кто-то в команде, кто мог бы просмотреть вашу документацию и предоставить обратную связь?
Комнат
Необходимость в этом очень похожа на побочные эффекты в других методах, которые вы явно используете.
Майкл Шоу

Ответы:

1

Если я правильно понимаю, у вас, похоже, есть уникальная проблема. То, что вы хотите сделать, это обратиться к конкретной строке кода в комментариях, которые написаны в какой-то другой части того же кода.

Я обычно не сталкиваюсь с такими сценариями, когда мне нужно сослаться на строку exect # в каком-либо комментарии, написанном в другом месте - обычно код документируется именно там, где он написан.

Я не знаю ни одного стандартного способа сделать это - но с головы до головы ...

Вы можете ссылаться на части кода через его контекст - то есть вещи, окружающие их.

Обратите внимание на определение func1 (), что такое-то происходит

Обратите внимание, что сразу после цикла for, который перебирает записьXYZItr, мы также вызываем метод gc ()

Внимание: в методе yahoo () сразу после объявления переменной PQ мы также меняем значения в A и B, поэтому объект mapABC также необходимо скопировать

Другой способ - добавить описательные теги. Вместо чего-то вроде 38FECD4F, вы можете сказать Some XYZ implementationили BUGFIX 1474, а затем сослаться на это где-то еще.

treecoder
источник
Спасибо за ответ! Я думаю, что «опишите его контекст» выглядит как лучший вариант для меня. Еще раз спасибо.
одинокий катер
2
Наличие уникальной проблемы довольно часто означает, что вы делаете что-то неправильно.
Тийс ван Дин
2
@ThijsvanDien: Поверь мне, мы делаем много вещей неправильно! ;-)
одинокая лодка
3

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

Но ... если вам нужно сослаться на конкретную строку кода как на единое целое, не будет ли это означать, что это какой-то код, представляющий абстрактную операцию и, следовательно, может быть реорганизован в свой собственный метод / функцию? Раз в методе, это довольно просто, просто обратитесь к. namespace.class.methodКонечно, это означает, что методы очень малы, около 5-10 строк или даже меньше. С Doxygen вы можете поместить документацию поверх метода, и она всегда будет синхронизирована с именем метода / класса / пространства имен.

Лоран Бурго-Рой
источник
1
Этот ответ должен быть победителем, за исключением первоначальной точки зрения ОП, что он покидает проект и, по-видимому, имеет ограниченное время, а также, по-видимому, не должен вносить изменения на своем выходе. Но абсолютно правильно - если что-то достаточно сложное, чтобы выдержать внешнюю ссылку, поместите его в свой собственный кодовый модуль.
Росс Паттерсон
2

Я предлагаю вам использовать другой подход, кроме ссылки из некоторой внешней документации по коду на код:

  1. добавьте комментарии к своему коду, используя такой инструмент, как doxygen .

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

Таким образом, вы можете легко сгенерировать документацию в виде веб-страницы или в формате PDF, и она будет соответствовать коду. Использование некоторых искусственных тегов станет очень трудно поддерживать и еще труднее понять для непосвященных.

miraculixx
источник