15、软件开发中的文档、文件组织与命名最佳实践

软件开发中的文档、文件组织与命名最佳实践

1. 文档编写的重要性与策略

在软件开发过程中，文档起着至关重要的作用。它不仅能为新功能的实现提供上下文，还能展示其与前后操作的依赖关系。PIM 倡导即时特性开发，其中就包含即时文档编写这一最佳实践。

在开始编码前，我们不应采用“大爆炸”式的方法，即提前记录所有内容再开始编码。不过，在着手新特性、故事或模块时，应先完成以下问题解决步骤：
- 创建详细的设计文档
- 绘制状态图、序列图、时序图等
- 完整定义并注释头文件内容的语义

完成这些步骤后，再进行编码。

2. 软件开发计划（SDP）

PIM 鼓励在项目开始、设计和实现之前生成软件开发计划（SDP）。SDP 记录了软件开发团队的开发过程细节，是团队成员遵循的操作规则。例如，它会指定使用的 SCM 和 bug 跟踪系统、SCM 分支约定、代码审查方式等。

在 SDP 最终确定之前，团队所有开发人员都应有机会审查并提供意见。SDP 适合放在 Wiki 页面上，它本质上是一系列决策、需求和约束的集合。以下是 SDP 可能包含的内容：
| 类别 | 具体内容 |
| ---- | ---- |
| SCM 相关 | SCM 仓库组织和位置、SCM 分支策略 |
| 过程模型 | Agile、TDD、瀑布等 |
| 编码标准 | 编码标准要求 |
| 文件组织 | 文件组织方式 |
| 代码审查 | 代码审查过程 |
| Bug 管理 | Bug 跟踪和生命周期 |
| 构建系统 | 构建系统相关 |
|