如何在文档中引用代码的特定区域？

我要离开一个项目，在我去之前，我的老板要我记录代码（我没有很好地记录文件）。这没什么大不了的，该项目并不复杂。但是我在我的文档中找到了一些要说的地方，“在XYZ行上通知某某某事”。

在这种情况下，引用特定的行号是没有意义的，因为添加或删除一行代码会立即使文档过期。是否有一些最佳实践来引用特定的代码行而不通过行号引用它？

我已经考虑过在代码中添加如下注释：

/* linetag 38FECD4F */

其中“ 38FECD4F”是该特定行的一些唯一标记。然后，我可以放入文档中，“在标记为'38FECD4F'的行上，注意这样的事情会发生。”

还有其他想法吗？我觉得通常最好记录整个代码单元，而不是记录它们的特定部分，但是在这个特定项目的情况下，会有大量的过程代码，这些代码从未被分解成较小的单元。

如果我理解正确，您似乎有一个独特的问题。您想要执行的操作是引用注释中的特定代码行，这些注释以同一代码的其他部分编写。

我通常不会遇到需要在其他地方写的注释中引用摘录行＃的情况，通常情况下，代码是在编写位置处记录的。

我不知道执行此操作的任何标准方法-但我无法解决...

您可以通过上下文来引用部分代码，即围绕它们的内容。

注意上面func1（）的定义

注意，在for循环上遍历recordXYZItr之后，我们还调用了方法gc（）

注意：在方法yahoo（）中，在声明变量PQ之后，我们还交换了A和B中的值，因此那里的mapABC对象也需要复制

另一种方法是添加描述性标签。38FECD4F您可以说Some XYZ implementation或而不是类似，BUGFIX 1474然后在其他地方引用它。

这在很大程度上取决于代码的编写方式，而且我了解这可能会导致大量重构工作，而您将无法进行此工作。

但是...如果您需要将特定的代码行作为一个整体来引用，这是否意味着它的某些代码代表了抽象操作，因此可以在其自身的方法/函数中进行重构？一旦将其引入方法中，它就非常简单，只需参阅即可namespace.class.method。当然，这意味着使用的方法非常小，大约5至10行，甚至更少。使用Doxygen，您可以将文档放在方法的顶部，并且始终与方法/类/命名空间的名称保持同步。

我建议您采用其他方法，而不是将某些代码外部文档链接到代码：

1. 使用doxygen之类的工具在代码中添加注释。

2. 如果需要在（新创建的）代码文档中适当地解释一些概念，则可以随时创建一个单独的文档并链接到该文档。

这样，您可以轻松地将文档生成为网页或PDF格式，并且与代码保持一致。对于一些初学者来说，使用一些人工标签将变得非常困难，甚至难以理解。