18、精确软件文档的重要性与编写要点

精确软件文档的重要性与编写要点

1. 合同中的文档

在软件开发合同中，规范说明是关键部分，它明确了可接受的交付成果。不过，规范说明不能与合同混为一谈，合同还涵盖了时间表、成本公式、惩罚条款、争议解决的司法管辖声明、保修条款等内容。

2. 文档与责任归属

即便在最出色的开发项目中，也可能出现问题。若没有清晰的文档说明每个组件的功能，开发团队之间就容易相互指责。而精确的文档能明确每个开发者的职责，便于将责任和成本归咎于相关方。

3. 文档与兼容性

现代软件开发方法追求组件的可互换性和可复用性，但组件间的兼容性并非偶然达成，需要清晰阐述可互换组件必须具备的特性。接口文档必须精确，否则软件组件很难实现互换。

4. 软件文档的成本与收益

4.1 增加人员导致的时间浪费

在项目进度滞后时增加新员工，可能会让项目更加滞后。新员工需要从原员工处获取信息，在此期间，原员工会花费大量时间为新员工讲解，导致工作效率降低。提供结构良好、精确且完整的设计文档，能帮助新员工更快上手，减少对原员工的打扰。

4.2 寻找答案的时间浪费

在修改或调试长程序时，无结构的文档或无文档的代码会让寻找关键细节变得十分耗时。软件进入维护阶段后，维护人员常常要花费超过一半的时间去理解代码的工作原理。结构合理、便于检索的文档能节省大量时间。

4.3 错误和不一致信息导致的时间浪费

开发团队为赶进度，可能只修改代码而不更新文档，或者文档更新不全面，导致文档出现不一致和部分错误。这会让程序员在修改和添加代码时浪费时间。