14、编程文档编写全攻略

编程文档编写全攻略

1. 文档的重要性

在编程领域，文档常常被开发程序员视为负担，但对维护程序员而言，它却是生命线。大多数程序员既承担开发工作，又要负责代码维护。当你数月未看自己写的代码时，它可能就像别人写的一样。编写代码时，年轻、聪明且乐观的你可能觉得记录代码的功能和实现方式很繁琐，但日后需要修复、扩展和调整代码的你，会珍视文档中保存的那些被遗忘的见解。从这个意义上说，文档是你写给未来自己的情书。

2. 文档的类型

• 用户文档与技术文档的区分 ：终端用户很少会阅读代码或注释，他们通常会使用 perldoc 命令查看模块或应用的文档。而维护人员和其他开发者除了查看 POD（Plain Old Documentation），还会花大量时间直接查看代码。因此，应将用户文档放在代码 POD 的“公共”部分（如 =head1 、 =head2 和 =over/=item/=back 部分），将技术文档放在“非公共”位置（如 =for 和 =begin/=end POD 部分以及注释）。
• 内容区分 ：用户文档和技术文档的内容应有所区别。尤其不要在用户文档中包含实现细节，这既浪费时间又会让用户厌烦。只需告诉用户代码的功能，而不是实现方式，除非这些细节与用户使用代码相关。例如，为用户记录一组列表操作时，只需说明 pick() 从列表中随机选择一个元素， shu