很多开发者忽略了文档的重要性。
再次打开自己半年前开发的某个项目,会发现思路几乎已忘得一干二净--当时自己做了什么?如何做的?为什么这么做?如果需要增添功能,没有文档的帮助,将会变得十分困难;零星的注释只能帮助代码片段的理解。因为项目已经生疏,需要将整个项目的代码从头到尾、一行一行重新吃透,唤醒大脑中该项目的记忆,才知道如何下手。如果有编写得当的文档,通过查阅文档能很快重新理解项目,也能很快找出与新增功能相关的部分。这将大大提高效率,同时节省了时间。
如果开发者参与团队开发,没有文档就是一场灾难了。当你向团队提交代码后,不得不向其他成员解释你写了什么?为什么这么写?当项目非常庞大时,开发者不可能完全理解其他成员的代码。以上这些都会对时间造成不必要的浪费。在团队开发中编写文档就像某种形式的沟通,同时能帮助其他成员理解自己的代码,毕竟每个人的代码风格都不同。让团队成员理解自己的代码是必不可少的任务。
3个主流的文档生成工具
注意
- 常见的tag有:@brief, @param, @return 完整列表
- @character是所有tag的前缀。
- 以上符号“@”可以替换为反斜线“\”(@brief变为\brief)。
- “\”一般用于Doxygen。
- “@”一般用于HeaderDoc。
- 使用“@”可以同时适用Doxygen和HeaderDoc。
- HeaderDoc只能识别/*! */格式的注释,而Doxygen能识别/*! */和/** */两种格式。
- 对于方法(method),生成HTML文档时只会识别头部文件中的注释,其他地方的注释只会在Xcode help显示,并不会加入到生成的HTML文档中。
- @field用于描述struct和霉女(Enum)中的单个变量,HeaderDoc能识别,而Doxygen不能。在struct中每个变量顶部用/*! */格式注释,两个工具都能识别。
- Xcode支持对@param标签中的参数名进行检查,可在Build Settings中开启。
参考
以下是三个工具的介绍和使用教程:
Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen