如何使大型代码库更容易理解

假设我正在开发一个相对较大的项目。我已经用Doxygen记录了我的所有类和函数，但是，我有个主意，在每个源代码文件上都写上“程序员笔记”。

这背后的想法是用通俗的术语解释一个特定的类是如何工作的（不仅是为什么大多数评论如此）。换句话说，让其他程序员对类的工作方式有另一种看法。

例如：

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

这是使大型项目更容易让新的程序员/贡献者理解其工作方式的好方法吗？除了保持一致的编码风格和“标准”目录组织外，针对这些情况是否还有“标准”或建议？

这太棒了。我希望更多的软件开发人员花时间和精力来做到这一点。它：

• 用简单的英语陈述班级的工作（即责任），
• 提供有关代码的有用的补充信息，而无需重复逐字逐句地说明代码，
• 概述了一些设计决策以及做出这些决策的原因，以及
• 突出显示下一个阅读您的代码的人可能会遇到的陷阱。

las，许多程序员陷入了“如果代码编写正确，就不必记录文档”的阵营。不对。在代码类，方法，模块和其他工件之间存在许多隐含的关系，这些关系从仅阅读代码本身来看并不明显。

有经验的编码人员可以精心设计出具有清晰，易于理解的体系结构的设计，而无需文档即可显而易见。但是您实际上看到过多少个这样的程序？

使用大型代码库的关键是不必阅读整个代码库即可进行更改。为了使程序员能够快速找到他要查找的代码，应该对代码进行组织，并使组织清晰可见。也就是说，代码中的每个逻辑单元，从可执行文件，库，命名空间，到单个类，都应有明显的责任。因此，我不仅要记录源文件，还要记录它们所在的目录。

程序员的注释也为设计决策提供了背景知识。尽管这可能是有价值的信息，但我会将其与责任说明分开（以使读者可以选择是否要阅读类的责任或它的设计原理），并将其移至与它描述的来源接近的地方。尽可能地提高代码在更新时文档更新的机会（仅当我们可以相信文档的准确性时文档才有用-过时的文档可能比没有文档更糟糕！）。

就是说，文档应该保持DRY，即不要重复可能已经用代码表达或已经在其他地方描述的信息（诸如“由于文档状态”之类的警告标志）。特别是，将来的维护人员将精通项目的编程语言，就像他们使用的是英语一样。用注释对实现进行释义（当人们为自己的文档感到骄傲时，我经常会看到它）没有任何好处，并且可能与实现有所不同，特别是如果文档与它描述的代码不符时。

最后，应在整个项目中对文档结构进行标准化，以便每个人都能找到它（这是错误跟踪中Peter文档的一团糟，在Wiki中是Sue，在自述文件中是Alan，在源代码中是John……） 。

我不同意这是一个很好的方法，主要是因为

1. 当您重构项目时，四处移动方法，文档就会中断。

2. 如果文档没有正确更新，将导致混乱，而不是帮助理解代码。

如果您具有针对每个方法的单元测试/针对每个模块的集成测试，则与代码注释相比，这将是一个更易于维护且更易于理解的自我文档。

是的，拥有适当的目录结构肯定会有所帮助。

我个人是高级设计文档的爱好者-最好在编写任何代码之前编写这些文档-该文档概述了设计，并提供了类和资源的列表。自上而下的设计大大简化了工作-您的操作可能是“游戏引擎->硬件->控制器->游戏杆”；因此，一个新的程序员告诉“修复'xyz控制器上的'a'按钮”至少会知道从哪里开始寻找。

太多的现代语言倾向于将代码分解为数百个小文件，因此，即使是中等规模的项目，要找到正确的文件也可能是一个挑战。

如果代码库很大，我将尝试提供一个设计文档，其中列出了其设计和实现的关键要素。这里的目的不是要详细说明所使用的任何类，而是要提供编码的关键和进入设计的思想。它为系统，其组件及其应用提供了一个总体上下文。

设计文件中应包括的内容是：

• 应用架构
• 逻辑代码结构
• 数据流
• 使用的关键模式及其使用的动机
• 代码源结构
• 如何构建它（这提供了对隐式依赖关系和物理代码源结构的深入了解）

之后，应该适当地完成有关类和函数/方法的文档。特别是公共API；应该清楚在每种情况下以下所有内容；

• 前提条件
• 特效
• 不变量
• 异常条件（抛出）

我发现使新开发者更容易理解代码库的最重要规则是完美的协议，代价很高。

如果新开发人员必须完全了解他们正在使用的系统，那么它将阻止所有机会在职学习。我认为程序员的笔记是一个很好的开始，但是我会走得更远。尝试编写新的代码，如果重新使用它们，它们将使开发人员能够实时确定自己在做什么，而不是要求他们先学习再做。对于您所知的情况，断言之类的小事情永远都不会发生，而解释断言为何有效的注释则大有帮助。如果您做错了任何事情，编写代码也会正常失败，而不是进行段错误。

我看到了带有文档的大型类，并且在阅读了文档之后，我不知道该类应该做什么，以及为什么有人会使用它！同时，我需要一些功能，并且我绝对确定必须有一个类来处理它，并且在任何地方都找不到它-因为没有文档将我从我需要的知识引导到该类。正在做。

因此，我在文档中想要的第一件事就是一句话，一个类做什么，以及为什么要使用它。原始问题中的评论在这方面做得很好。阅读这些注释后，如果我有一个由于无法解释其提供的值而无法正常工作的操纵杆，我将知道要检查的代码。

类似于@meriton所说的，将代码分解为单独的组件。更好的是，将代码库分解为单独的程序包（JAR，Gem，Eggs等），以使组件的分离更加清晰。如果存在错误，则开发人员仅需要找到该错误所在的包，并且（希望）仅将其修复。更不用说，单元测试更容易，并且您可以利用依赖管理。

另一个解决方案：缩小代码库。代码越少，越容易理解。重构出未使用或重复的代码。使用声明式编程技术。当然，这很费力，而且通常是不可能或不实际的。但这是一个值得的目标。正如杰夫·阿特伍德（Jeff Atwood）所写：最好的代码根本没有代码

对于复杂的系统，不仅要记录每个文件，还要记录它们的交互作用和层次结构，以及程序的结构和原因，这是值得的。

例如，游戏引擎通常非常复杂，在经过数百层抽象之后，很难确定什么叫什么。可能需要创建一个类似“ Architecture.txt”的文件来解释代码的结构以及为什么如此，以及为什么那里没有毫无意义的抽象层。

这可能部分是因为单个程序员很难编写它，因为每个人都只能理解他们的项目部分。

有时您可以从项目经理的注释中获取此信息，但这仅是您将获得的，因为他们很少会用这种格式重写其注释。