Documentation 向团队成员展示/解释代码和设计决策

我正在从事一个项目，在这个项目中，我必须定期向与我不直接参与同一项目领域的团队成员证明并解释我的代码和设计决策

---

我如何才能最好地向位于不同地点的团队成员解释我的技术设计决策？对于没有直接参与的团队成员来说，代码演练值得花时间吗？还是书面解释和注释代码更好？如果我决定对我的代码进行大量注释以解释设计决策，那么我是否应该在单独的代码副本中进行注释？

在实际代码中添加好的注释，包括简短的示例，请参见alsos等。
确保在签入结果中包含生成的HTML帮助
（使其他人更容易访问文档）

在解决方案/项目中还包括演示项目/软件包，演示您的设计优势以及如何使用您的代码。

---

确保示例与其他人正在研究的主题相连接，这将使他们更容易连接。

IMHO，很好地注释代码可能是传达此信息的最佳方式。随着代码库的发展，大型手册甚至设计文档很快就会过时。除此之外，程序员不太可能坐下来翻阅一本厚厚的手册，而更不可能去翻阅代码以了解发生了什么

如果您的代码设计得足够好，其结构是自文档化的，那么您添加的注释将解释您的算法，这将提供其他程序员理解您的代码所需的其余信息

---

如前所述，提取注释以生成多种语言的API文档非常容易。这是另一件有用的事情。

我喜欢手工绘制简单的图表，用于设计说明。但是你必须让它非常简单，不要用完整的架构图和每一个小细节使它过载。围绕图表与同事交谈将使其成为一次很好的讨论，如果他们就此提出问题，那么时间比你自己的演讲更有价值

说到编写代码文档，我非常喜欢干净的代码。如果您仔细命名所有内容，那么如果代码背后真的有一个设计决策让您选择了一种不寻常的方式，那么您应该只删除一行注释。我通常避免在代码中使用大量文档（比如javadoc）

我是这样做的：

• 保持方法简单
• 1您的方法的详细程度
• 变量、方法、类的好名称

我还试图避免代码中的黑客行为。如果您需要解释代码中的一行代码，因为您使用了最奇特和最短的方式来完成任务，那么您可能会让下一个开发人员发疯

---

而且，重要的是：为您的代码提供测试用例（可能是单元测试），以便其他开发人员可以运行它们，查看发生了什么，并实际查看您的代码打算如何使用。我认为，将测试用例作为记录代码的一种方式，对于其他开发人员来说是一种非常好的习惯您的代码的方式。同样的规则也适用于测试用例而不是代码：保持干净。

我自己也遇到过这个问题。我最终会回答我所做的，但我想留下这个问题不回答，看看其他人有什么建议。问得好！（+1）我支持Pablo（+1），但如果您使用.Net或Java，将源代码注释放入帮助文件中非常有用。。。。Trac也是如此，但前提是每个人都能读代码。提到测试用例和单元测试时+1。