在私人和公司中，我或我们的开发人员反复评论我们的代码实际上是一个问题，但通常没有人确切知道整个项目的代码如何协同工作。当我编写自己的代码并且项目变得越来越大时，我有时也会遇到这个问题。虽然我写了大量的 cmets，但 3 个月后你不知道整个事情到底是做什么的，这意味着不同的方法和类是如何协同工作的。
您如何在您的公司或私下解决这个问题（如果只是边缘项目开发而没有需求规范）。或者您是否总是拥有如此出色的项目开发合同文档和需求规范，以至于您不必担心这一点？
【问题讨论】：
标签： java project-management comments project
Code complete 可以比我更好地解释您的问题的解决方案。
【讨论】：
我发现解决这个问题的最佳方法是使用单元测试框架编写功能测试。
在功能测试中，您编写的测试加载了几个（如果不是全部）裸露的核心组件。这表明所有组件都可以正常工作，而且您还会获得一份文档，该文档在一个地方向您展示了所有组件的连接方式。
根据交互的复杂程度，您可能还不够，需要记录下来。就我个人而言，我更愿意使代码简单，这样就不需要记录它或者相对容易解释。
如果记录它听起来太难，那么是时候重构你的代码了。
【讨论】：
花点时间创建一些简短的设计文档，添加一些 UML 图来展示整个应用程序背后的基本思想。这将使新的团队成员快速概览。在内部 wiki 上发布此文档，并鼓励团队在必要时进行改进。
然后，正如 Peter 建议的那样，一些有据可查的测试用例确实很有帮助：阅读测试代码并学习如何使用 API。 （并且，作为一个次要效果，测试代码;-)）
我不会在 cmets 上投入太多精力，尤其是在线 cmets。往往会过时，因为没有单元测试可以验证行 cmets 仍然有效，甚至值得，没有人删除不必要的 cmets。
【讨论】：
好问题。您所问的部分内容与代码可维护性有关。在我看来，您可以做两件事来改善这一点：-
根据过去的经验，由于时间限制，第一项在软件项目中经常被忽略，但我认为如果您至少可以生成系统的类图，那么这对于理解对象如何几个月后重新访问代码时进行交互。根据复杂性，序列图也很有用。制作此文档也将有助于团队的新成员快速了解软件的结构。
编写清晰和可维护的代码的重要性怎么强调都不为过。当我读到罗伯特马丁的Clean Code 时，我的眼睛最近睁开了。你应该至少阅读本书的前几章，这对你自己和你的开发人员同事都有责任。仅此一项就可以立即提高代码的可读性和可维护性。
这个想法是代码应该读起来几乎像一个叙述，其中方法按照逻辑顺序，简短，适当命名，并且使用很少的参数。这样做几乎消除了对代码 cmets 的需求，并改进了代码结构。
【讨论】：