在文档中添加外部链接是不好的做法吗？

9

我通常会通过在Stack Overflow上找到答案来解决错误。添加我为什么要做的代码片段，然后从网络添加指向文章或页面的链接，这是不好的做法吗？

documentation

— 真相42
source

可能的重复，我应该添加MSDN笔记或堆栈溢出链接到源代码？

— t

FWIW我一直都这样做，甚至问如何在StackExchange上正确地做到这一点。它不能回答您的问题，但是可以在那找到一些支持和反对的论点。

4

可能的重复项是否可以在程序的注释中添加指向Q＆A网站的链接？

— 布朗

这是仅关于链接的问题吗（对我来说很好），因为您还提到了复制部分代码/答案。我只是为了解释复杂的算法或处理而做。无论您在何处了解解决方案，代码结构和命名都应清晰明了。

— Kwebble

14

我不认为这很糟糕，但是外部链接在整个解决方案的生命周期中都有一个坏习惯。这样做时，建议您添加足够的摘要，以在链接不再起作用时为读者提供帮助。

— 吉姆·拉什（Jim Rush）
source

3

添加有用的摘要有两个原因：1）正如Jim所指出的那样，它有助于读者理解链接是否过时，以及2）迫使开发人员从链接中复制代码以了解他们正在复制什么。这有助于确保不仅仅因为“它解决了问题”而使用了代码。

— 法师Xy

7

这就是公司应该拥有自己的知识库的原因。例如，我的公司有一个法人化的Redmine，用于项目管理，票证（错误和任务跟踪）以及我最常用的工具wiki。每个项目的所有这些功能:-)

我们在项目的Wiki上有什么？

链接到文档：功能，技术，体系结构，需求。
参与的参与者：项目经理，开发人员，客户的大客户经理，...
每个环境的描述：虚拟机，操作系统，服务器，配置...
杂项：在项目生命周期中学到的任何重要/有趣的事情（与项目相关）。
更多页面。

我将参考书目（链接）放在Misc Wiki中。但只有那些我相信的人：

堆栈溢出：赞成票，有充分争议
软件工程Stackexchange：赞成票且论据充分
MKyong.com：我喜欢这个页面。这真的很有用，教程也很容易遵循
MDN
W3C.org
W3Schools：它的文档是交互式的（在大多数情况下）并且用户友好。
OWASP：用于引用与安全性和漏洞有关的问题
官方网页：有时最好的教程或解释在官方网页上。

我的参考书目中附有我所键入的摘要，以确保我了解我要链接的内容。我尝试使Javadoc尽可能清晰。代码中的每个链接都引用Redmine的Wiki或Redmine的发行代码。

在没有Redmine之类的工具的情况下，我发现有用的Markdown文件可用于这些目的。由于这些文件的开发人员总体上在SCM中，并且附带了代码。

— 莱夫
source

1

除了信任W3Schools.com，我同意所有其他方式。您可以在MDN上找到大部分具有更多权限的功能。

— Alternatex

1

W3schools的存在时间比MDN长。我可能是错的，但我认为W3schools有更多内容，教程和Web技术文档。尽管存在问题，它仍然是初学者的最佳参考之一，因为它的内容更加人性化和交互式。从正面看，MDN有一个很棒的社区来支持其内容。但不利的一面是，它的文档永远都不可能公正，因为它具有浏览器可以防御。无论如何，我同意你的看法，如今MDN似乎拥有更多的权限。如果您不介意，我会将参考添加到我的答案中。

— Laiv

4

链接到网络作为文档有些问题，因为互联网不能保证您在它们后面看到的内容与将来的文档阅读器所看到的相同。如果可能，请尝试仅链接到极不可能更改的资源。

例如，当您链接到Wikipedia时，应显式链接到当前版本，而不是通用文章名称。对于stackexchange.com来说，目前看来似乎不可能消失，但是问题总是会被编辑甚至删除，并且在五年的时间内可能会出现一个新的热点。我不会冒着将具有实质业务价值的文档悬挂在您的组织外部的网站上的风险。

— 基利安·福斯（Kilian Foth）
source

“ Wayback Machine-Internet存档”（web.archive.org/）是检查已删除内容的好地方。

— Kromster