超链接的外部源代码文档

Question

为什么我们仍然将源代码的自然语言描述(即编写一行代码的原因)嵌入到源代码中，而不是作为单独的文档？

考虑到为现代开发环境(高分辨率监视器、双监视器等)提供的广阔的房地产，IDE可以提供半锁定步骤的面板，其中源代码在视觉上与其相应的注释--但本质上是链接--分开。例如，开发人员可以用超链接标记语言(链接到附加的软件需求)编写源代码注释，这将同时防止文档混乱源代码。

有哪些缺点会阻碍这样的软件开发机制？

一个模拟来帮助澄清这个问题：

当游标位于源代码中的某一行时(上面以蓝色背景显示)，则突出显示与游标处的行对应的文档(即，与其他细节相区别)。正如问题中所指出的，当游标跳过源代码时，文档将与源代码保持锁定步骤。热键可以在“文档模式”和“开发模式”之间切换。

潜在的优势包括：

• 更多的源代码和更多的文档立刻出现在屏幕上(S)
• 独立于源代码编辑文档的能力(不管语言如何？)
• 并行编写文档和源代码，不发生合并冲突
• 具有高级文本格式的实时超链接文档
• 准实时机器翻译成不同的自然语言
• 每一行代码都可以清楚地链接到任务、业务需求等。
• 文档可以在编写每一行代码时自动时间戳(度量)。
• 动态包含架构图、图像来解释关系等。
• 单源文档(例如，用于用户手动包含的标记代码段)。

注意：

• 文档窗口可以折叠。
• 查看或比较源文件的工作流不会受到影响。
• 如何实现是一个细节；文档可以是：
  • 保存在源文件的末尾；
  • 按约定分成两个文件(filename.c、filename.c.doc)；或
  • 全数据库驱动

• 所谓超链接文档，我指的是链接到外部源(如StackOverflow或维基百科)和内部文档(即子域上的wiki，可以交叉引用业务需求文档)和其他源文件(类似于JavaDocs)。

相关线程：为什么不喜欢这个行业的文档？

Answer 1

这个问题一直困扰着我，我只是对我们应该尝试解决这个问题的方向有了一个想法(这就是我发现这个问题的原因)。

我认为，当我们决定将用户文档包括在源代码中时，链接文档问题被认为是错误的。就像多科一样。

首先，让我们将代码注释与用户文档区分开来。

代码注释通常是最好的，当它们是短的，超短的，事实上，所以我可以阅读代码做的东西，而不必看一些诗歌，它为什么和如何工作。

用户注释是为试图使用您的库/API的人准备的，其中可能包括使用示例、解释为什么会这样实现，或者说明如何扩展库。这类评论往往很冗长。

我确实同意这样一个事实，即文档应该用纯文本编写，所以供应商不是固定的，而且很容易添加到VCS中。但我认为将用户文档保存在源文件中是一个很大的错误，至少有两个原因：

• 更难读的代码
• 文档不够灵活(假设我需要使用相同的示例代码的两个文档页，或者有一个文档页需要从两个不同的源文件中交织代码)。

那我们为什么要把它放在同一个文件里呢？好吧，没人想让他们的文档与代码不同步。但无论如何，我们都会这么做，特别是现在，在Markdown取得巨大成功的日子里。我认为这是正确的道路，但如果失败了，那就走得太短了。

当我们将代码注释与用户注释交织在一起时，我们有一个双向绑定。这样我们就可以很容易地看到哪个注释对应于代码的哪个部分。我们还可以看到一些代码是否是无文档的。它没有提供的是一种查看注释是否被更新的方法，当您的代码很难阅读时(因为文档使它变得很难看)，这种情况经常发生。

如果我们不是有双向绑定，而是有一个单向的呢？指向代码的文档。我们可以使用特殊命令进行标记代码，例如：

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

这样做的好处是通过添加一些附加的标记，并且通过适当的工具，我们可以为它增加更多的价值。

想象一下，这种方式可以与诸如grunt之类的工具绑定(甚至与监视任务绑定)。您可以检测源文件何时更改，查看哪些文档文件依赖于它，并警告用户(或者在某个地方标记它)，如果注释的代码发生了更改。

Answer 2

404 -找不到

在使用代码时，您不希望注释丢失，当您将代码和注释分离为单独的文档时，就会发生这种情况。

此外，保持注释文档和代码文档之间的版本化将带来更多的痛苦。

您提出的一些建议，我非常喜欢，但可以很容易地实现，同时也有一个文件的代码和注释。

Answer 3

我所看到的可能的缺点是：

• 您需要一个实现此功能的特殊编辑器。
• 代码不再仅仅是纯文本，更易于操作和提交到VCS-es。
• 要使用代码，需要增加两倍的屏幕宽度。

至于你的论点：

更多的源代码和更多的文档立刻出现在屏幕上(S)

但如果您想同时查看两个文件，则可能会很不方便。

独立于源代码编辑文档的能力(不管语言如何？)

我认为这实际上是一个不利因素。我个人试图使文档尽可能接近代码，这样它就不会过时。

并行编写文档和源代码，不发生合并冲突

再说一次，这可能是个不利因素。如果您的文档与代码深深交织在一起，您如何能够独立地编辑它们？

具有高级文本格式的实时超链接文档

如果它在代码中，它已经是实时的;)至于超链接，跳到定义已经在大多数IDE中实现了。

准实时机器翻译成不同的自然语言

我不明白为什么您不能用常规的注释/docstring来实现这一点。

每一行代码都可以清楚地链接到任务、业务需求等。

这个我不确定..。难道不能通过定期的评论来实现吗？

文档可以在编写每一行代码时自动时间戳(度量)。

VCS-es不是已经提供了这样的信息吗？

尽管如此，我非常喜欢布局本身--但我不认为有必要更改文件格式，从常规评论中生成它并不那么困难。有很多文档生成器可以做到这一点，例如多科及其后继者，如皮科或边缘。