如何编写代码文档，为什么软件（通常）文档记录不佳？

有一些很好的示例，这些示例都记录了很好的代码，例如java api。但是，公共项目（例如git和公司的内部项目）中的许多代码都没有很好的文档记录，并且不是很新手。

在我所有的软件开发工作中，我不得不处理文档记录不佳的代码。我注意到以下情况-

1. 代码中很少或没有注释。
2. 方法和变量名不是自描述的。
3. 很少或没有文档说明代码如何适合系统或业务流程。
4. 雇用不良的开发者或不指导好的开发商。他们不能编写简单干净的代码。因此，包括开发人员在内的任何人都很难或不可能编写代码。

结果，我不得不阅读大量代码并与许多人交谈以学习事物。我觉得这浪费了大家的时间。它还为项目的新手带来了KT /知识转移会话的需求。

我了解到，由于以下原因，文档没有得到应有的重视：

1. 懒惰。
2. 开发人员只喜欢编写代码就什么都不喜欢。
3. 就业保障。（如果没有人能轻易理解您的代码，那么您可能就很难被替换。）
4. 艰难的截止日期几乎没有时间记录在案。

因此，我想知道是否有一种方法可以鼓励和执行公司或项目中的良好文档规范。无论项目的复杂性如何，用于为任何项目的系统和代码创建体面文档的策略是什么？有什么很好的例子，说明什么时候需要最少的文档或根本不需要文档？

恕我直言，我认为我们应该在项目交付后对文档进行审查。如果它不简单，简洁，说明性和用户友好性，则开发人员或技术文档工程师将对此负责，并负责对其进行修复。我既不希望人们编写大量文档，也不希望它像第一本书一样对用户友好，但是我希望它消除了数小时的分析和浪费的KT会话。

有没有办法结束或减轻这种疯狂？也许是“文档驱动的开发”？

如何记录代码？

您已经有了一个提示：看看如何记录Java API。

更一般而言，没有适用于每个项目的唯一规则集。当我从事关键业务的大型项目时，该文档与我为小型开源库编写的文档无关，而后者又与我的中型个人项目的文档无关。 。

为什么许多开源项目的文档记录不正确？

因为大多数开源项目都是由为这些项目做出贡献的人们制作的，因为这很有趣。大多数程序员和开发人员认为编写文档不够有趣，无法免费完成。

为什么许多封闭源项目没有得到很好的记录？

因为（1）编写好的文档并（2）维护它会花费大量金钱。

1. 利益相关者可以清楚地看到直接成本（编写文档的成本）：如果您的团队要求在接下来的两个月中花时间对项目进行文档化，则还要多付两个月的薪水。

2. 对于经理来说，长期成本（维护文档的成本）也变得很容易，并且通常是他们必须降低成本或缩短延迟的首要目标。这导致了过时文档的另一个问题，该问题很快变得毫无用处，并且更新非常昂贵。

3. 另一方面，长期的节省（无需花几天时间去浏览遗留代码只是为了了解应该已经记录在案的基本知识而节省下来的费用）很难衡量，这证实了一些管理者的感觉。编写和维护文档是浪费时间。

我经常观察到的是：

1. 刚开始时，团队愿意提供大量文档。

2. 随着时间的流逝，截止日期的压力和缺乏兴趣使维护文档变得越来越困难。

3. 几个月后，实际上加入该项目的新人无法使用该文档，因为它根本与实际系统不符。

4. 注意到管理层将开发人员未维护文档归咎于管理层。开发人员要求花几个星期进行更新。

   • 如果管理层为此花了几周的时间，则重复该周期。

   • 如果管理层根据以前的经验拒绝，则只会增加不良经验，因为该产品缺少文档，但是花了几个月的时间编写和维护它。

就像测试一样，文档应该是一个连续的过程。花一个星期简单地编码数千个LOC，然后回到测试和文档是非常非常痛苦的。

如何鼓励团队编写文档？

与鼓励人们编写简洁代码，进行常规重构，使用设计模式或添加足够的单元测试的方法类似。

• 以身作则。如果您编写好的文档，您的同伴也可能会开始这样做。

• 进行系统的代码审查，包括旨在检查文档的正式代码审查。

• 如果团队中的某些成员特别讨厌好的文档（或完全没有文档），请与他们私下讨论该主题，以了解阻碍他们编写更好文档的哪些障碍。如果他们指责时间不足，您会发现问题的根源。

• 在数周或数月内衡量是否存在文档，但不要专注于此。例如，您可以测量每个LOC的注释行数，但不要使其成为永久性度量，否则，开发人员将开始写长而无意义的注释，以摆脱低分。

• 使用游戏化。这与上一点结合在一起。

• 使用正/负加强筋。

• （请参阅SJuan76的评论）将缺少评论的内容视为错误。例如，在Visual Studio中，您可以选中一个选项来生成XML文档。如果您还检查所有警告均被视为错误，则类或方法顶部缺少注释将停止编译。

  至于前三点，应谨慎使用这一点。我在一支特别艰苦的初学者程序员团队中使用了一段时间，最后得到了与StyleCop兼容的注释，例如：

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

嗯...不是特别有用。

切记：当程序员想要与您纠缠时，没有自动化可以帮助您查明不良评论。只有代码审查和其他人工任务才有帮助。

有什么很好的例子，说明什么时候需要最少的文档或根本不需要文档？

不需要解释架构和设计的文档：

• 对于原型

• 对于花费几个小时编写的个人项目来完成一项任务，同时确保不会再维护此项目，

• 对于任何显而易见的项目，鉴于其规模很小，再加上特别干净的代码，与将来所有探究该代码的维护者相比，您将花费更多的时间来编写文档。

根据一些开发人员的说法，当代码是自我记录时，不需要代码内记录文档（代码注释）。对于他们来说，除了在极少数情况下之外，注释的存在不是一个好兆头，而是一个迹象，表明该代码没有足够的重构以至于无需注释即可清晰可见。

我觉得在项目交付后，我们应该对文档进行审查。

如果您的项目每周至少交付一次，那么这就是方法。如果您的项目不是敏捷的，并且每六个月交付一次，请进行更多定期审查。

我认为您应该在注释和文档之间进行区分。尽管注释是描述性的，但缺乏一致性，它们分散在整个代码中。注释永远不能弥补自我描述不足的代码，而应该向其他程序员提示棘手的部分。

是否应记录代码取决于项目的规模。当然，有些人认为应该将所有内容都记录在案，并且似乎很容易证明这种想法是正确的，因为谁敢反对记录知识？幸运的是，软件开发不是科学，如果您的小程序背后的细节变得晦涩难懂，世界不会崩溃。现在，有关供许多开发人员使用的专业软件，很显然，您应该记录代码。但是，如果您能够在该级别进行编码，那么您显然会知道这一点。

tl; dr

如果您要对每个项目进行充分的记录，那么您的要求就太多了。