你的技术文档是什么样子的？

Question

我正在为一个大型项目工作，我想为团队的其他成员和加入该项目的新程序员收集一些技术文档。

我应该有什么样的文件？只是///代码注释或其他一些文件(S)解释了体系结构和类设计？

我从来没有真正做过文档，除了偶尔的word文档与较小的应用程序，我认为这个项目太大，无法在一个word文件文档。

Answer 1

我写了以下信，并从中受益：

• 解释系统或单个组件作为一个整体的体系结构文档。这些都是很好的新员工阅读，以了解“大图”，你的东西如何运作。通常，它们包含高层图表，说明系统的不同部分如何相互通信，以及对系统的每个组件、其作用等的解释。
• 正式的设计文档；在编写这些文档时，每个文档都考虑到一个特定的特性，并经过正式的评审过程。虽然这些并不总是保持最新的几年后，他们提供了很好的洞察力的每一个单独的特点。本文档列出了形式需求、数据流图、类图，并按技术领域(数据库、中间件、用户界面等)详细介绍了对系统的修改。然而，在事后写这些可能很困难(如果不是不可能的话)。如果这些文档对您的团队有意义的话，最好的选择是将它们作为开发过程的一部分。
• 代码中可以转换为API文档(如JavaDoc )的注释。这些都是很好的参考，在一个更低的层次上解释事情。

您可能不是准备这些文件的人，但它们也可能很有用：

• 用户手册，指南等-对于新的雇用，这些可能有助于获得一个不同的角度，如何实际的产品是缩进，以供您的客户使用。
• 测试计划--读起来非常乏味，更多的是“交互式文档”，但有时新员工学习的最好方法是在实际系统上运行测试用例。

需求文档也可能有帮助，这取决于它们编写得有多好，不过老实说，我发现其他形式的文档对于理解系统的工作方式更有用。需求文档更适合驱动您的设计工作。

Answer 2

对于新手来说，你也应该简要地记录你的源代码结构、签入/退出过程、在哪里找到工具等等。然后，当一个新人上船时，让他们更新文档，并添加他们觉得缺少的东西。

Answer 3

我强烈建议您通过强力氧原并适当地编辑源文件。然后运行doxygen，它将生成足够的技术文档，如类层次结构等。

实际上，将doxygen作为构建过程的一部分，并在您进行时继续遵循注释约定。

仅仅是架构和类设计本身并不足以满足大型项目的需要。这是最低标准：

1. 请记录全局变量。没有例外。
2. 如果函数正在修改其输入以外的任何内容，请指定相同的内容。
3. 任何一些例行公事所做的不平凡的事情。特别是，如果您正在实现一些复杂的算法，请包含对该算法的引用url或纸张。
4. 已知的黑客，你的投入，并承诺自己将在周末修复它。