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

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

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

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

/* linetag 38FECD4F */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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