当前位置: 首页 > news >正文

Android开源项目规范总结

前言

由于开源项目的不断增多,我们的开发效率也得到了极大的提升,但是开源项目往往不能够完全的match我们的需求,我们可能只是依赖其中的部分功能,但是为此我们需要将一堆臃肿的代码带入到我们的项目中,为了解决这个问题,需要我们能够很好地理解源码,然后将我们需要的核心功能,从代码中将其抽离出来,来适应我们的项目,而我们作为一个开源项目作者,作为一个负责的开源项目的作者,就要求我们要能够写出规范易懂,便于阅读的代码,因此需要我们有规范的代码命名规范,整洁的代码规格,同时拥有良好的文档,为了方便开发者的使用,我们还需要有良好的README来说明我们的项可以实现的功能,项目可能会出现一个平台兼容性上的问题,或者是使用上的一些问题,因此需要我们提供一个FAQ来帮助开发者解决一些粒度较大的问题,对于每一次的功能迭代,版本更新,我们都需要提供版本更新说明。

代码命名规范

  • 基本命名规范

    • 代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束

    • 代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式

    • 杜绝完全不规范的缩写,避免望文不知义

  • 包名

    • 包名为小写

    • 点分隔符之间有且仅有一个自然语义的英语单词,包名中单词统一使用单数形式

  • 类名

    • 类名必须是一个名词,每个单词首字母大写。除了约定俗成的缩写,尽量使用完整单词

    • 实现类如果和接口区分,请在接口名后加Impl

    • 抽象类命名使用Abstract或Base开头

    • 异常类命名使用Exception结尾

    • 测试类命名以它要测试的类的名称开始,以Test结尾

    • 如果使用到了设计模式,建议在类名中体现出具体模式,有利于阅读者快速理解架构设计思想

    • 枚举类名建议带上Enum后缀

  • 方法名

    • 动词或动词+名词

    • 采用驼峰命名方式,第一个单词首字母小写,其它单词首字母大写

  • 变量名

    • 采用驼峰命名方式,首字母小写,其后单词的首字母大写

    • 内部使用的变量加m前缀

    • 静态变量加s前缀

    • 控件名不需要和 id 名一致,采取统一的缩写前缀

  • 常量名

    • 使用static final前缀,全部大写,单词间用下划线隔开,并且指出完整含义

    • 不推荐使用枚举,推荐在接口中定义常量字段

  • 类成员位置顺序:(类中顺序按如下自顶向下)

    • 静态常量

    • 静态变量

    • 成员变量

    • 构造方法

    • 成员方法

    • 静态类方法

    • 内部类以及内部接口

代码规格

流程控制

  • 嵌套For/If/Try最大深度3

  • 在if/else/for/while/do语句中必须用"{"和"}"括起来,避免引起没必要的错误

  • 对于多个的if/else 尽量把高概率匹配的放在前面,提高性能

  • 循环语句:尽量不要改变循环变量的值

  • switch语句:对于多分支语句,建议使用switch语句,每个条件都要加break,在每一个switch块内,都必须包含一个default语句并放在最后,即使它什么代码也没有

空行以及换行

垂直

单行空行在以下情况使用

  • 类成员间需要空行隔开:例如成员变量、构造函数、成员函数、内部类、静态初始化语句块、实例初始化语句块

  • 成员变量之间的空白行不是必需的。一般多个成员变量中间的空行,是为了对成员变量做逻辑上的分组

  • 在函数内部,根据代码逻辑分组的需要,设置空白行作为间隔

  • 类的第一个成员之前,或者最后一个成员结束之后,用空行间隔(可选)

  • 单空行时使用多行空行是允许的,但是不要求也不推荐

水平

  • 使用Tab进行控制,推荐使用Android Studio默认的规范

字符编码

一律使用utf8编码

  • String:String.getBytes()编码统一使用utf-8,代码文件编码统一使用UTF-8

  • URL编码:请使用URLEncoder. encode(s, “utf-8”)方法

XML规则

资源命名规则

  • 基本命名规范

    • 命名中单词均采用小写

    • 单词之间采用下划线分割

  • layout xml资源命名

    • activity或fragment对应的layout资源,一级标识为activityfragment,例如:activity_media_picker.xml

    • 对于模块资源,一级标示资源类型,二级标示业务类型,比如:view_login_xxx.xml

    • 全局共享的资源:二级前缀可省略或使用app,例如:view_app_xxx.xml

    • listview或recycleview的item,一级标识为item例如:item_xxx.xml

  • drawable目录的资源:(包含图片以及xml)

    • 现在临时放置在这个文件夹下的图片,后面需要删掉,命名为 tmp_XXXXX

    • xml 定义的 drawable 资源放置在这里

    • 其他正式要用的图片,主要放置在 drawable-xhdpi 文件当中,其他需要适配的图片文件自行放置在其他对应的目录下面

    • 多个模块公用的图标命名为 ic_XXXX,背景图片命名为 bg_XXXX

    • 具体模块单独使用的图片命名为 modulename_XXXX (如 userpage_XXXX)

    • selector 对应的 xml 命名为 selector_XXXX

    • shape 对应的 xml 命名为 shape_XXXX

    • 文件名最好能描述内容信息,命名模板property(属性)_function(功能)_color/size(颜色/大小)_state.png,例如ic_switch_white_on.png

  • colors

    • 通用的颜色直接使用名称,如redgreen

    • 部分通用颜色,可以直接添加数字,如灰色(gray_aa, gray_f1

    • 根据页面模块分组,注释说明,空行隔开

    • 具体页面相关的颜色,前面带上页面逻辑相关的名称。例如login_btn_gray_666666,对于已有色彩采用间接引用,不存在直接引用16进制颜色代码

  • dimens

    • 通用的半径、文字大小,可以分别定义成 radius_4dptext_15sp等等

    • 其它和具体业务逻辑相关的,前带上页面逻辑相关的名称

    • 对于已经存在的尺寸采用间接引用

ID命名规则

  • 统一使用前缀表明类型,比如btn_xxx,仅在布局使用的控件(不在代码中使用),id使用layout_xxx前缀

  • 命名单词均采用小写,通过下划线分隔

  • 命名二级标识页面模块,例如btn_login_login

  • 缩写前缀列表(欢迎补充),自定义控件使用字母缩写

控件类型缩写前缀
Viewv
Buttonbtn
ImageViewimg
ImageButtonimgBtn
TextViewtv
ListViewlv
RecycleViewrv
LinearLayoutll
RelativeLayoutrl
FrameLayoutfl

Gradle规范

build.gradle(Project:ProjectName)规范

buildscript代码块

  • dependencies声明android gradle plugin的版本为最新版本(只需要保证二级版本为最新版),例如:

classpath 'com.android.tools.build:gradle:2.x.x'

build.gradle(Module:app)规范

编译相关规范

  • sdk版本号以及构建工具版本使用最新的release版本

 compileSdkVersion 2x
 buildToolsVersion "2x.0.0"
  • 设置代码的编译版本为1.7,使编译出的包更通用

 compileOptions { 
        sourceCompatibility JavaVersion.VERSION_1_7 
        targetCompatibility JavaVersion.VERSION_1_7
 }

defaultConfig代码块规范

  • targetSdkVersion,同compileSdkVersion版本

    • minSdkVersion 指定成11,android 4.0,原则上不支持4.0以下系统

    • ndk无硬性规定,非特殊的情况,只需在lib目录中保留arm架构的so库

signingConfigs签名规范

debug版本使用默认设置,release版本的签名文件不得出现硬编码密码在build.gradle文件中,请将storePassword、keyAlias以及keyPassword密码放在properties文件中便于管理,示例:

signingConfigs {
    debug {
       storeFile file('debug.keystore')
    }
    release {
       // keystore
       storeFile file('release.keystore')

       // keys
       Properties properties = loadProperties('release.properties')

       storePassword properties.get('storepassword')
       keyAlias properties.get('keyalias')
       keyPassword properties.get('keypassword')
   }
}
 

buildTypes代码块规范

  • shrinkResources 是否取消无效资源,去除无效资源有利用减少包大小,但会减慢编译速度,建议在release版本中开启

  • minifyEnabled在混淆时去除代码中无用的内容,建议在release中开启,包含插件的项目中不允许开启此选项

  • zipAlignEnabled 资源包对齐,可提升执行速度,减少内存消耗,release模式下必须打开

dependencies代码块规范

  • 为规避库冲突,请使用远程依赖的模式,指定groupId、artifactid以及版本号

  • 需要使用本地依赖的情况,请通过compile files逐个指定文件名,不允许通过compile fileTree指定文件夹

  • 本地依赖包需指定groudId,artifactId以及版本号,例如com.facebook.fresco-fresco-0.8.1.jar

  • 如无必要,勿增实体:如果你的app没有support,multi包需求,请勿添加依赖

  • exclude android库,例如:exclude support包

  • 尽可能使用lib,避免module依赖,独立工程可以通过aar或mvn方式导入;原因:

    • rebuild成本过大

    • 构建工具版本混乱

    • 未来涉及插件化非DSL脚本时,复杂度几何上升

版本管理规范

  • 使用最新的二级动态版本

  • 使用ext拓展,统一定义版本号

  • 为提高可读性,建议将名称改为小写缩写,例如

ext {
    target_sdk_version = 24
}

权限规范

尽量避免Android 6.0敏感规范,例如:

  • 手机状态

  • 位置信息(建议使用服务端IP定位)

  • 读写SD卡(优先使用拓展目录)

JavaDoc规范

遵循原则

  • 每个开放给用户的函数/类,必须在文档中

  • 准确描述其中每个参数/成员的取值

  • 仅用于内部的函数/类,不要在文档中暴露给用户(可以另编简要的开发者文档作为记录)

  • 对于描述,尽可能的详细,全面

具体实施

  • 类的描述

    • 类的作用

    • 使用样例

  • 接口/抽象类

    • 作用

    • 框架提供的实现

  • 方法的描述

    • 传递参数的类型,含义

    • 返回值的类型,含义

    • 传递参数值的范围对于程序执行的影响

    • 方法产生的作用

README书写规范

  • 框架的集成方式

  • 简要的Getting Started(入门)或者一个详细些的Tutorial(教程)

  • 对于常用或者暴露给用户的所有接口的Example(使用实例)

FAQ规范

  • 去解答一些大尺度、共性的疑问

  • 不要将一些小的问题也都类似单个函数的使用等加入进来

版本更新声明

  • 新增功能

  • 解决问题

相关文章:

  • PHP 使用 Redis
  • MySQL 高可用性—keepalived+mysql双主(有详细步骤和全部配置项解释)
  • Visual Studio 版本管理从TFS迁移到SVN
  • write-ahead-log与append-only-file的原理
  • sass中的三种循环
  • 【腾讯Bugly干货分享】经典随机Crash之一:线程安全
  • 基于Docker搭建Redis主从
  • Centos6.5安装lvs+keepalived集群
  • FTP服务系列一FTP的基础知识以及服务器端的配置
  • vsftpd.conf 详解与实例配置
  • swift中UISearchBar的使用
  • MSP项目群管理介绍
  • cmake 添加头文件目录,链接动态、静态库(转载)
  • Phantomjs v.2.1 addCookie()始终返回错误
  • 在shell中编写函数
  • 分享的文章《人生如棋》
  • Dubbo 整合 Pinpoint 做分布式服务请求跟踪
  • happypack两次报错的问题
  • Java比较器对数组,集合排序
  • Java教程_软件开发基础
  • Js基础知识(四) - js运行原理与机制
  • Linux后台研发超实用命令总结
  • npx命令介绍
  • PAT A1017 优先队列
  • 动态规划入门(以爬楼梯为例)
  • 对超线程几个不同角度的解释
  • 复习Javascript专题(四):js中的深浅拷贝
  • 记录:CentOS7.2配置LNMP环境记录
  • 前嗅ForeSpider采集配置界面介绍
  • 三分钟教你同步 Visual Studio Code 设置
  • 提升用户体验的利器——使用Vue-Occupy实现占位效果
  • 一个普通的 5 年iOS开发者的自我总结,以及5年开发经历和感想!
  • 源码安装memcached和php memcache扩展
  • 在GitHub多个账号上使用不同的SSH的配置方法
  • Unity3D - 异步加载游戏场景与异步加载游戏资源进度条 ...
  • #传输# #传输数据判断#
  • #我与Java虚拟机的故事#连载18:JAVA成长之路
  • (二)换源+apt-get基础配置+搜狗拼音
  • (每日持续更新)信息系统项目管理(第四版)(高级项目管理)考试重点整理第3章 信息系统治理(一)
  • (十二)python网络爬虫(理论+实战)——实战:使用BeautfulSoup解析baidu热搜新闻数据
  • (原創) 如何優化ThinkPad X61開機速度? (NB) (ThinkPad) (X61) (OS) (Windows)
  • (转) Android中ViewStub组件使用
  • (转)http-server应用
  • (转)德国人的记事本
  • (总结)Linux下的暴力密码在线破解工具Hydra详解
  • *Django中的Ajax 纯js的书写样式1
  • .gitignore
  • .Net 高效开发之不可错过的实用工具
  • .NET开源全面方便的第三方登录组件集合 - MrHuo.OAuth
  • .NET框架
  • .Net转Java自学之路—SpringMVC框架篇六(异常处理)
  • .php结尾的域名,【php】php正则截取url中域名后的内容
  • .pings勒索病毒的威胁:如何应对.pings勒索病毒的突袭?
  • @requestBody写与不写的情况
  • [ 代码审计篇 ] 代码审计案例详解(一) SQL注入代码审计案例