关于Android开发文档

论文档的重要性

对自身的重要性

每个人的精力都有限，不可能一直持续codeing一份代码直至毫无BUG的运行。长时间不阅读维护时文档可以让我们很快的捡起来

对项目的重要性

一个项目从发现需求线索，到需求调研，整理需求并分析可行性，再分解需求交付到开发者手中。过程中如果没有文档，客户会并不知道钱和时间都花在那儿，对交付的项目进行二次开发或维护也将会是噩梦。再到后来客户就不敢再把项目给你了。

对产品的重要性

开发者往往把项目和产品分的很细，但项目和产品就是相互衍生的关系。不同与项目，产品的延续性对于文档的要求苛刻。因为产品这东西要得到市场的认可，这东西就一直在自己手中打磨，随着时间的推移市场的变化总会做出不断的调整和摸索。不谈代码可测试，完整的文档才能够让重构和扩展变得轻松些

对团队的重要性

一个人的精力终归有限，团队的协作能够快速完成项目或快速推出产品抢占市场。开发过程中同一个项目和产品，不同的小伙伴负责不同的块。比如淘宝业务中单单一个弹窗也有一个部门，可见分工之细。那么不同模块就应该对外提供清晰的文档，以提高使用效率。

怎样写Android文档

Android程序往往只是系统中的一端，但要考虑的方面方面一点也不少。在一开始开发就要考虑到设备的差异、架构、技术选型等等，其他很多开发规约文档Android也同样适用。

毕竟代码是机器运行的，文档和注释是给人看的，所以文档和注释要有一定的通读性。借助一些工具和现有的规约，从如何入手Android项目到方方面面讨论怎么写文档

运行环境

Android程序当然运行在Android设备上，但Android硬件设备千差万别，所以有必要描述运行环境，定制化设备还需要描述硬件信息。

运行环境示例：

• 最小Android版本 5.1
• 最大适配到Android13
  外部接口：
• RJ 45有线网口
• Wiegand接口 1. 12V, 2. GDN，3. WG-D1输入,4. WG-D0输入

开发环境

开发环境的描述有助于团队开发统一工具、插件和库，避免使用last版本导致的升级问题。

开发环境示例：

• jdk version 1.8
• kotlin version 1.6
• gradle version 7.0.2

构建

构建项目是运行的第一步，构建包含了外部模块和依赖。同一个产品可能有不同的构建维度，比如免费版，订阅版本，永久VIP版。收费版有增值服务，那么应该描述构建和功能差异。
构建示例：

1. 模块：

• lib_sensor 硬件感知层模块

• lib_face 人脸模块

2. 维度：

• 免费版 基础功能

• 订阅版 同步服务

• VIP版本 所有功能永久使用

维度功能描述使用了锚点，可跳转到功能项目

注释

类文件

kotlin文件创建时可以依赖工具模板自动填充日期、作者信息，再添加类描述信息

/**
 *@Date 2022/4/19
 *@Author 锅得铁
 *@Deprecated 一组*成员*。
 *
 * 这个类没有有用的逻辑; 它只是一个文档示例。
 *
 * @param T 这个组中的成员的类型。
 * @property name 这个组的名称。
 */
class Group<T>(val name: String) {

}

方法

方法应该描述该方法的入参，返回，特别是对外开放的public方法必须。

/**
* 将 [member] 添加到这个组。
* @return 这个组的新大小。
*/
fun add(member: T): Int { …… }

常量

常量一般用/** 注释**

/**
* 取得日当前人数
*/
const val TAB_NAME = "api_log"

变量

变量用//注释

var index = 0//下标从0开始

清单文件

清单文件描述了页面信息使用

<!-- 设置页面-->
<activity
     android:name=".ui.setting.SettingsActivity"
     android:exported="true">
</activity>

样式

<!-- 编辑框标题文字样式-->
<style name="EditTextSettingsTitle" parent="Widget.AppCompat.TextView">
   <item name="android:textColor">#8C8C8C</item>
   <item name="android:textSize">26sp</item>
</style>

借助Doc工具

kotlin也有和Java doc类似的工具 KDoc

具体的使用方法参见Kotlin KDoc
工具源代码和详细说明参见github KDoc

发布

发布时不单单要提供给用户变更信息，开发人员也应该有发布变更文件

发布变更示例：

v1.0.2

• 新增优博讯扫码设备的支持
• 优化扫码模块
• 修复盘点扫描手动输入添加数量仅+1问题

v1.0.1

• 折扣商品打印折扣区间变更为从服务端获取
• 新增自动更新功能

v1.0.0

• 开始接手盘点助手应用

代码提交

提交代码时code review 的角色不一定有，但要有code review的视角，注释是否明确，命名是否有通读性。

提交时SVN后者git限制5字真言（忘记写注释不给提交）

提交备注示例

1. 新增自动更新功能
2. 修复了手动输入数量仅+1异常
3. 删除了冗余的工具类
4. 重构了扫码抢模块
5. 优化了二叉树排序算法
6. 集成人脸模块
7. 完成人证合一

备注具有回溯性，再加上提交的版本号可以很好的比较差异或者回滚