如何确保应用程序源代码有适合新程序员的文档？

Question

可能重复: 多少文件就足够了？

您知道像IBM、Microsoft或google这样的大型IT公司如何确保他们的应用程序源代码为未来的新程序员提供适当的文档吗？他们的方法或技术是什么？他们是告诉程序员编写文档，还是聘请专门的技术编写人员来完成这一任务？文档化是在一个单独的文件中还是在源代码本身中(以注释/注释的形式)？或者是另一种我不知道的方法？

我之所以这么问，是因为在我的经验中，我看到大多数IT公司(在我的国家)都非常懒惰地强加应用程序文档编写文化。所以，当一个新的程序员进来的时候，问题总是会发生，他总是会面临这样的情况:他被告知要阅读和学习大量的源代码，而没有文档。当然，他可以请高级程序员向他解释，但有时高级程序员忙于他们的工作，所以他们不情愿地想帮助你，有时可能更糟的是，只有一个懂代码的程序员已经辞职了。因此，您将单独使用源代码:(

不知何故，我能理解程序员写评论或文档的懒惰，因为程序员的工作已经很辛苦，而且他们的代码和测试过程也很乏味。更别提最后期限了--贝尔或愤怒的老板总是在背后萦绕着他们。我无法想象程序员在长时间的代码输入之后，不得不再次输入文档时，会多么痛苦和劳累。

对于技术作家来说，我从来没有和他们打交道过。我怀疑技术编写人员是否有用，因为完全理解源代码的人是程序员自己。在这种情况下，程序员必须陪同技术编写人员解释源代码。

注意:我指的是源代码或应用程序开发文档，而不是用户文档/指南，我认为这是由系统分析师或业务分析师编写的。开发文档通常包含有关应用程序开发的技术信息，如:应用程序特性、类/功能引用、类关系图、数据库信息、网络信息等。而用户文档则更多地涉及到应用程序为最终用户提供的信息。

Answer 1

不幸的是，没有办法“正确地”文档源代码。主要原因如下：

1. 你知道些什么？如果你是一个学徒，你将需要比，比如说，有70K堆叠溢出和黄金java徽章的人更详细的文档。你怎么能事先知道在你公司开始的人会知道什么，以及你需要在文档中解释什么？
2. 如何保持文档和代码保持同步？通过多种方式验证代码:单元测试、代码评审，以及在生产中运行代码。如果文档是错误的，必须有人阅读并注意到。这意味着文档的使用速度要比代码快得多，人们很快就开始不信任和忽略它，这使得它的老化速度更快。
3. 你什么时候写文件？早？这就增加了文档存在的可能性(参见前面的一点)。迟到了？增加了这件事还没做完的可能性-永远不会。
4. 你记录了什么？一万英尺的鸟瞰？最有用的，并有最大的机会保持有用的时间，但大多数情况下无用--比如说，当你追捕一只虫子。
5. 你为什么要写文件？只是为了让管理层高兴？他们懂得什么？或者，由于代码太差，所以需要编写文档吗？不如写可读的代码来代替呢？

我对有意编程抱有一些希望，但这还没有实现。

基于25+多年的经验，我目前的方法是首先编写可读代码，并将文档工作投入到单元测试中：

• 单元测试不能说谎
• 它们必须很简单(4-10行代码)
• 他们一个接一个地解释代码的每个特性。
• 它们运行速度很快(我们公司的规则是所有单元测试必须在不到10s内运行)

从我们公司开始的人可以在调试器中运行，点击2-3鼠标，看看代码是如何工作的。

最大的优势是:无论如何，您需要编写单元测试。为什么不把它们也用于文档呢？

Answer 2

一个词-过程。我在航空航天行业工作，有一个过程需要将某些工件作为软件开发周期的一部分生成。QA中的另一个过程确保生成这些工件。评审过程确保生成的工件满足所需的细节和准确性水平。另一个过程削弱了其他过程的成功，等等。

这远非完美，也不便宜，做任何事情都需要付出很大的努力。开发人员可以在不阅读和理解每一行代码的情况下维护数百万行代码库。我知道没有其他方法可以做到这一点。“代码就是福音”的编码器在面对这些生命关键的、实时复杂的系统时不幸失败。文档并不能100%准确地反映代码所做的事情，但它比代码更接近于代码应该做什么的描述。因此，如果代码没有按照文档的要求执行，那么代码可能是错误的。

我们不使用科技作家；然而，我认为我们应该--程序员并不总是优秀的英语作家，开发一位技术作家，把笨拙的技术势利转化为简洁的英语，对IMHO来说是一笔小投资。

Answer 3

我不喜欢文件。它可以说谎，代码不能。无论如何，都有关于应用程序的更高级概念的文档，但是记录代码呢？这是一个很大的迹象，表明您的代码不清楚。

不过，我使用高级语言(主要是C#)编写代码，即伪英语，其他使用更低级别语言的人可能不同意。