源代码注释中的交叉引用

Question

有时，当您编写程序时，您需要在注释中引用其他部分/或函数。例如，在下面的代码中，我可以在注释中设置两个锚点“workaround1”和“workaround2”（在另一个文件中），并通过引用相关注释来记录ABC函数。

// this part does <<workaround1>>
a = 1;
a++;
...

// [[workaround1]] and [[file:c.java::workaround2][2]] can be removed once ABC is fixed
c = ABC();

我有两个问题：

1. 这种参考是否有最佳实践？专业程序员如何处理它？<​​/ li>
2. 是否有针对emacs的软件包可以通过源代码注释来导航这些笔记？我正在考虑组织模式扩展，可以在（最好是任何）语言模式之上工作。

我知道关于Redmine的类似问题：Can I create a cross-project source reference in redmine?

Answer 1

毫无疑问，有不同的方法可供选择。有人可能会描述如何使用org-mode，这可能是最常用的方法。就个人而言，我使用linkd.el - 简单。你可以得到它here。

我在Emacs-Lisp文件中使用它，但您可以在任何文本文件中使用它。

标题或命名目标看起来像纯文本：

      ;; (@* "Common helper functions")

对于Lisp而言，其中;开始发表评论。在您的情况下，我相信您会使用//。

来自同一文件的链接如下所示：

      ;; (@> "Common helper functions")

来自不同文件的链接如下所示：

      ;; (@file :file-name "foo.el" :to "Common helper functions")

但它们是使用突出显示来渲染的，没有无关的字符。

目的地如下（但突出显示）：

      * Common helper functions

同一文件链接如下所示（但突出显示为Emacs链接，并带有鼠标悬停突出显示）：

      > Common helper functions

不同的文件链接如下所示（但突出显示为链接，带鼠标悬停）：

      . foo.el : Common helper functions