超链接的外部化源代码文档

源代码为什么我们仍然嵌入自然语言描述（即，原因为何一行代码编写）的源代码中，而不是作为一个单独的文件？

鉴于为现代开发环境（高分辨率监视器，双监视器等）提供了广阔的房地产，IDE可以提供半锁式面板，其中源代码在视觉上与-而是与-内在链接其相应的注释。例如，开发人员可以使用超链接的标记语言（链接到其他软件要求）编写源代码注释，这将同时防止文档造成源代码混乱。

哪些缺点会抑制这种软件开发机制？

一个有助于澄清问题的模型：

当光标位于源代码中的特定行（上面以蓝色背景显示）时，与光标所在行相对应的文档将突出显示（即，与其他详细信息区分开）。正如问题中指出的那样，当光标在源代码中跳转时，文档将与源代码保持同步。热键可以在“文档模式”和“开发模式”之间切换。

潜在优势包括：

• 一次在屏幕上显示更多源代码和更多文档
• 能够独立于源代码编辑文档（无论语言如何？）
• 并行编写文档和源代码，而不会发生合并冲突
• 具有高级文本格式的实时超链接文档
• 准实时机器翻译成不同的自然语言
• 每行代码都可以清楚地链接到任务，业务需求等。
• 文档可能会在每行代码编写时自动加盖时间戳（指标）
• 动态包含架构图，解释关系的图像等。
• 单一来源的文档（例如，用于用户手册的标签代码段）。

注意：

• 文档窗口可以折叠
• 查看或比较源文件的工作流程不会受到影响
• 实施过程如何进行是一个细节。该文档可能是：
  • 保存在源文件的末尾；
  • 按约定（filename.c，filename.c.doc）分为两个文件；要么
  • 完全由数据库驱动
• 通过超链接文档，我的意思是链接到外部源（例如StackOverflow或Wikipedia）和内部文档（即子域上的Wiki，可以交叉引用业务需求文档）和其他源文件（类似于JavaDocs）。

相关主题：业界对文档的厌恶是什么？

这个问题无时无刻不在困扰着我，我对如何解决这个问题有了一个思路（那就是我发现这个问题的方式）。

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

首先，让我们区分代码注释和用户文档。

代码注释通常在简短时（实际上是超级简短）处于最佳状态，因此，我实际上可以阅读执行该注释的代码，而不必了解其原因和工作方式的诗篇。

用户注释供尝试使用您的库/ 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之类的工具绑定（甚至与watch任务绑定）。您可以检测到源文件何时发生更改，查看哪些文档文件依赖于该文件，并在注释的代码已更改的情况下警告用户（或在某处标记出该文件）。

404页面不存在

在使用代码时，您不希望注释迷路，这就是将代码和注释分离到单独文档中时发生的情况。

同样，保持注释文档和代码文档之间的版本控制会带来更多的痛苦，然后再增加麻烦。

您真正喜欢的一些建议，但可以轻松实现，同时在1个文件中包含代码和注释。

我看到的可能的缺点：

• 您需要一个特殊的编辑器来实现此功能

• 该代码不再只是纯文本，更易于操作并提交给VCS-es

• 您需要两倍以上的屏幕宽度才能使用代码

至于你的论点：

一次在屏幕上显示更多源代码和更多文档

但是如果要并排查看两个文件，可能会很不方便。

能够独立于源代码编辑文档（无论语言如何？）

我认为这实际上是不利的。我个人试图使文档尽可能地接近代码，以免过时。

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

再次，可能是不利的。如果您的文档与代码有很深的交织，那么如何独立编辑它们？

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

如果在代码中，则它已经是实时的；）对于超链接，大多数IDE已经实现了跳转到定义的操作。

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

我不明白为什么不能使用常规注释/文档字符串来做到这一点。

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

我对此不确定，不能通过定期评论来实现吗？

文档可能会在每行代码编写时自动加盖时间戳（指标）

VCS-es尚未提供此类信息吗？

话虽如此，我还是很喜欢布局本身，但是我看不到需要更改文件格式，因此从常规注释中生成它并不难。有大量的文档生成器可以做到这一点，例如Docco及其后继者，例如Pycco或Marginalia。

首先，文档注释需要与代码一起使用-将它们移到其他位置只会使事情难以实现，几乎无法实现零收益。那么，为什么要打扰！

但是，可以做的是获取那些嵌入的注释，并将其隐藏在编辑器中，并根据需要在气泡或工具提示中显示它们。我希望这种方法可以鼓励人们为代码编写更多的文档-例如，类的描述可以与该类一起使用，而不是在外部设计文档中使用。

您目前可以在代码注释中嵌入超链接，并且可以使用Doxygen或Sphinx之类的工具从代码生成文档。我想代码编辑器需要花哨的扩展才能更好地支持这些工具。

我不会将任何代码行链接到错误跟踪器或需求工具，这对于您的SCM来说是更好的选择。然后，您可以查看链接到任务的每次提交的代码编辑。我也不会针对错误跟踪器集成代码中存储的文档-如果您想迁移到新版本（嗯，我现在可以看到此功能已添加到TFS中），您将一头雾水。丢失了提交历史（发生这种情况）

除了@Bogdan已经声明的内容之外，我还要添加一些内容：

• 我将IDE配置为一次总是拥有2个文件。使用您建议的功能，基本上，我将需要2台显示器来查看相同数量的信息，并需要3台显示器来完成我现在正在做的事情。
• 在浏览文件时，您不会立即看到注释，并且如果您不确切知道要查找的内容，则很难找到它。
• 在搜索文件时，我无法直接（或同样容易）搜索注释。
• 有时我需要通过ssh进行各种测试/在实时服务器上编写短代码。尽管您说的功能可以与VIM或其他命令行编辑器集成，但很可能会出现很大的问题

• 大多数IDE支持折叠代码/注释，最终结果如下：

  而不是正常的：

  

使代码更具可读性，以防您不需要注释。

源代码和文档应采用的方式。

http://jasmine.github.io/2.3/introduction.html