rsi*_*deb 5 documentation communication
我正在开展一个项目,我必须经常向那些没有直接参与项目相同领域的团队成员证明和解释我的代码和设计决策.
我怎样才能最好地向不同地点的团队成员解释我的技术设计决策？对于没有直接参与的团队成员,代码演练是否值得花时间,或者书面解释和带注释的代码会更好吗？如果我决定大量评论我的代码来解释设计决策,那么我应该在代码的单独副本中这样做吗？
我喜欢手绘简单的图表来解释设计。但你必须保持它非常简单，不要用完整的架构图和每一个小细节来超载它。与您的同事围绕该图进行讨论将使其成为一次很好的讨论，如果他们提出有关该图的问题，那么时间比您自己的演讲更有价值。
在记录代码方面，我是“干净代码”的忠实粉丝。如果您仔细命名所有内容，那么只有在代码背后确实存在设计决策使您选择不常见的方式时，才应该删除一行注释。我通常会避免在代码中使用大量文档（例如 javadoc）。
这就是我所做的：
我还尝试避免代码中出现黑客行为。如果你需要解释代码中的一行，因为你使用了最奇特、最短的方法来做事情，你可能会让下一个开发人员发疯。
而且，最重要的是：为您的代码提供测试用例（也许是单元测试），以便其他开发人员可以运行它们，看看会发生什么，并实际了解您的代码的用途。我认为使用测试用例作为记录代码的一种方式对于其他开发人员来说是习惯您的代码的一种非常好的方式。相同的规则适用于测试用例和代码：使其干净。