Skip to content

Commit 6daf80a

Browse files
BlankjBlankj
committed
see the log
1 parent 343b498 commit 6daf80a

File tree

1 file changed

+51
-33
lines changed

1 file changed

+51
-33
lines changed

‎README.md

Lines changed: 51 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525

2626
1. 尽量使用最新版的 IDE 进行开发；
2727
2. 编码格式统一为 **UTF-8**；
28-
3. 编辑完 .java、.xml 等文件后一定要 **格式化**（基本格式方面使用 AS 默认模板即可）；
28+
3. 编辑完 .java、.xml 等文件后一定要 **格式化，格式化，格式化**（如果团队有公共的样式包，那就遵循它，否则统一使用 AS 默认模板即可）；
2929
4. 删除多余的 import，减少警告出现，可利用 AS 的 Optimize Imports（Settings -> Keymap -> Optimize Imports）快捷键；
3030
5. Android 开发者工具可以参考这里：**[Android 开发者工具][Android 开发者工具]**；
3131

@@ -38,7 +38,7 @@
3838
3939
#### 3.1 包名
4040

41-
包名全部小写，连续的单词只是简单地连接起来，不使用下划线，采用反域名命名规则，全部使用小写字母。一级包名是顶级域名，通常为 `com`、`edu`、`gov`、`net`、`org` 等，二级包名为公司名，三级包名根据应用进行命名，后面就是对包名的划分了，关于包名的划分，推荐使用按功能分，一开始我们也是按照层去分包的，很坑爹。按照功能分可能你不是很好区分在哪个功能中，不过也比你按照层区分要好找很多，具体可以参考这篇博文：**[Package by features, not layers][Package by features, not layers]**。且 PBF（按功能分包 Package By Feature）与 PBL（按层分包 Package By Layer）相比较有如下优势：
41+
包名全部小写，连续的单词只是简单地连接起来，不使用下划线，采用反域名命名规则，全部使用小写字母。一级包名是顶级域名，通常为 `com`、`edu`、`gov`、`net`、`org` 等，二级包名为公司名，三级包名根据应用进行命名，后面就是对包名的划分了，关于包名的划分，推荐采用 PBF（按功能分包 Package By Feature），一开始我们采用的也是 PBL（按层分包 Package By Layer），很坑爹。PBF 可能不是很好区分在哪个功能中，不过也比 PBL 要好找很多，且 PBF 与 PBL 相比较有如下优势：
4242

4343
* package 内高内聚，package 间低耦合
4444

@@ -89,7 +89,7 @@
8989
9090
PBL 中包的大小无限增长是合理的，因为功能越添越多，而 PBF 中包太大（包里 class 太多）表示这块需要重构（划分子包）。
9191
92-
当然，我们大谷歌也有相应的 Sample：**[todo-mvp][todo-mvp]**，其结构如下所示，很值得学习。
92+
如要知道更多好处，可以查看这篇博文：**[Package by features, not layers][Package by features, not layers]**，当然，我们大谷歌也有相应的 Sample：**[todo-mvp][todo-mvp]**，其结构如下所示，很值得学习。
9393
9494
```
9595
com
@@ -209,18 +209,18 @@ com
209209
| `handleXX()`, `processXX()` | 对数据进行处理的方法 |
210210
| `displayXX()`, `showXX()` | 弹出提示框和提示信息，使用 display/show 为前缀标识 |
211211
| `updateXX()` | 更新数据 |
212-
| `saveXX()` | 保存数据 |
212+
| `saveXX()`, `insertXX()` | 保存或插入数据 |
213213
| `resetXX()` | 重置数据 |
214214
| `clearXX()` | 清除数据 |
215-
| `removeXX()` | 移除数据或者视图等，如 `removeView()` |
215+
| `removeXX()`, `deleteXX()` | 移除数据或者视图等，如 `removeView()` |
216216
| `drawXX()` | 绘制数据或效果相关的，使用 draw 前缀标识 |
217217
218218
219219
#### 3.4 常量名
220220
221221
常量名命名模式为 `CONSTANT_CASE`，全部字母大写，用下划线分隔单词。那到底什么算是一个常量？
222222
223-
每个常量都是一个静态 `final` 字段，但不是所有静态 `final` 字段都是常量。在决定一个字段是否是一个常量时，考虑它是否真的感觉像是一个常量。例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。
223+
每个常量都是一个 `static final` 字段，但不是所有 `static final` 字段都是常量。在决定一个字段是否是一个常量时，得考虑它是否真的感觉像是一个常量。例如，如果观测任何一个该实例的状态是可变的，则它几乎肯定不会是一个常量。只是永远不打算改变的对象一般是不够的，它要真的一直不变才能将它示为常量。
224224
225225
```java
226226
// Constants
@@ -242,9 +242,13 @@ static final String[] nonEmptyArray = {"these", "can", "change"};
242242

243243
#### 3.5 非常量字段名
244244

245-
非常量字段名以 `lowerCamelCase` 风格的基础上改造为如下风格：基本结构为 scopeVariableNameType。
245+
非常量字段名以 `lowerCamelCase` 风格的基础上改造为如下风格：基本结构为 `scope{Type0}VariableName{Type1}`、`type0VariableName{Type1}`、`variableName{Type1}`。
246246

247-
**scope：范围**
247+
说明：`{}` 中的内容为可选。
248+
249+
> 注意：所有的 VO（值对象）统一采用标准的 lowerCamelCase 风格编写，所有的 DTO（数据传输对象）就按照接口文档中定义的字段名编写。
250+
251+
##### 3.5.1 scope（范围）
248252

249253
非公有，非静态字段命名以 `m` 开头。
250254

@@ -266,31 +270,40 @@ public class MyClass {
266270

267271
使用 1 个字符前缀来表示作用范围，1 个字符的前缀必须小写，前缀后面是由表意性强的一个单词或多个单词组成的名字，而且每个单词的首写字母大写，其它字母小写，这样保证了对变量名能够进行正确的断句。
268272

269-
**Type：类型**
270273

271-
考虑到 Android 中使用很多 UI 控件，为避免控件和普通成员变量混淆以及更好达意，所有用来表示控件的成员变量统一加上控件缩写作为后缀（文末附有缩写表）。
274+
##### 3.5.2 Type0（控件类型）
275+
276+
考虑到 Android 众多的 UI 控件，为避免控件和普通成员变量混淆以及更好地表达意思，所有用来表示控件的成员变量统一加上控件缩写作为前缀（具体见附录[UI 控件缩写表](#ui-控件缩写表)）。
272277

273-
对于普通变量一般不添加类型后缀，如果统一添加类型后缀，请参考文末的缩写表。
278+
例如：`mIvAvatar`、`rvBooks`、`fl_container`。
274279

275-
用统一的量词通过在结尾处放置一个量词，就可创建更加统一的变量，它们更容易理解，也更容易搜索。
276280

277-
例如，请使用 `mCustomerStrFirst` 和 `mCustomerStrLast`，而不要使用 `mFirstCustomerStr` 和 `mLastCustomerStr`。
281+
##### 3.5.3 VariableName（变量名）
282+
283+
变量名中可能会出现量词，我们需要创建统一的量词，它们更容易理解，也更容易搜索。
284+
285+
例如：`mFirstBook`、`mPrevBook`、`curBook`。
278286

279287
| 量词列表 | 量词后缀说明 |
280288
| ------- | ----------- |
281289
| `First` | 一组变量中的第一个 |
282290
| `Last` | 一组变量中的最后一个 |
283-
| `Next` | 一组变量中的下一个变量 |
284-
| `Pre` | 一组变量中的上一个 |
291+
| `Next` | 一组变量中的下一个 |
292+
| `Prev` | 一组变量中的上一个 |
285293
| `Cur` | 一组变量中的当前变量 |
286294

287-
说明：
288295

289-
集合添加如下后缀：List、Map、Set
296+
##### 3.5.4 Type1（数据类型）
290297

291-
数组添加如下后缀：Arr
298+
对于表示集合或者数组的非常量字段名，我们可以添加后缀来增强字段的可读性，比如：
292299

293-
> 注意：所有的 VO（值对象）统一采用标准的 lowerCamelCase 风格编写，所有的 DTO（数据传输对象）就按照接口文档中定义的字段名编写。
300+
集合添加如下后缀：List、Map、Set。
301+
302+
数组添加如下后缀：Arr。
303+
304+
例如：`mIvAvatarList`、`userArr`、`firstNameSet`。
305+
306+
> 注意：如果数据类型不确定的话，比如表示的是很多书，那么使用其复数形式来表示也可，例如 `mBooks`。
294307
295308

296309
#### 3.6 参数名
@@ -510,10 +523,10 @@ public static MainFragment newInstance(User user) {
510523

511524
#### 4.7 行长限制
512525

513-
代码中每一行文本的长度都应该不超过 100 个字符。虽然关于此规则存在很多争论，但最终决定仍是以 100 个字符为上限，如果行长超过了 100，我们通常有两种方法来缩减行长。
526+
代码中每一行文本的长度都应该不超过 100 个字符。虽然关于此规则存在很多争论，但最终决定仍是以 100 个字符为上限，如果行长超过了 100（AS 窗口右侧的竖线就是设置的行宽末尾 ），我们通常有两种方法来缩减行长。
514527

515528
* 提取一个局部变量或方法（最好）。
516-
* 应用换行将一行换成多行。
529+
* 使用换行符将一行换成多行。
517530

518531
不过存在以下例外情况：
519532

@@ -618,7 +631,7 @@ public Observable<Location> syncLocations() {
618631

619632
命名规则：`{模块名_}逻辑名称`。
620633

621-
说明：`模块名` 为可选，`逻辑名称` 可由多个单词加下划线组成。
634+
说明：`{}` 中的内容为可选，`逻辑名称` 可由多个单词加下划线组成。
622635

623636
例如：`refresh_progress.xml`、`market_cart_add.xml`、`market_cart_remove.xml`。
624637

@@ -656,7 +669,7 @@ public Observable<Location> syncLocations() {
656669

657670
命名规则：`类型{_模块名}_逻辑名称`、`类型{_模块名}_颜色`。
658671

659-
说明：`模块名` 为可选；`类型` 可以是[可绘制对象资源类型](可绘制对象资源类型)，也可以是控件类型（具体见附录[UI 控件缩写表](#ui-控件缩写表)）；最后可加后缀 `_small` 表示小图，`_big` 表示大图。
672+
说明：`{}` 中的内容为可选；`类型` 可以是[可绘制对象资源类型](可绘制对象资源类型)，也可以是控件类型（具体见附录[UI 控件缩写表](#ui-控件缩写表)）；最后可加后缀 `_small` 表示小图，`_big` 表示大图。
660673

661674
例如：
662675

@@ -702,7 +715,7 @@ public Observable<Location> syncLocations() {
702715

703716
命名规则：`类型_模块名`、`类型{_模块名}_逻辑名称`。
704717

705-
说明：`模块名` 为可选。
718+
说明：`{}` 中的内容为可选。
706719

707720
例如：
708721

@@ -714,14 +727,18 @@ public Observable<Location> syncLocations() {
714727
| `fragment_music_player.xml` | 音乐片段的播放器 `类型_模块名_逻辑名称` |
715728
| `dialog_loading.xml` | 加载对话框 `类型_逻辑名称` |
716729
| `ppw_info.xml` | 信息弹窗（PopupWindow） `类型_逻辑名称` |
717-
| `item_song.xml` | 歌曲列表项 `类型_逻辑名称` |
730+
| `item_main_song.xml` | 主页歌曲列表项 `类型_模块名_逻辑名称` |
718731

719732

720733
#### 5.5 菜单资源文件（menu/）
721734

722735
菜单相关的资源文件应放在该目录下。
723736

724-
命名规则：`{模块名_}逻辑名称`，`模块名_` 为可选，例如：`main_drawer.xml`、`navigation_menu.xml`。
737+
命名规则：`{模块名_}逻辑名称`
738+
739+
说明：`{}` 中的内容为可选。
740+
741+
例如：`main_drawer.xml`、`navigation.xml`。
725742

726743

727744
#### 5.6 values 资源文件（values/）
@@ -847,7 +864,7 @@ public Observable<Location> syncLocations() {
847864

848865
#### 5.7 id 命名
849866

850-
命名规则：`view缩写_{模块名}_逻辑名`，例如： `btn_main_search`、`btn_back`。
867+
命名规则：`view缩写{_模块名}_逻辑名`，例如： `btn_main_search`、`btn_back`。
851868

852869
如果在项目中有用黄油刀的话，使用 AS 的插件：ButterKnife Zelezny，可以非常方便帮助你生成注解；没用黄油刀的话可以使用 Android Code Generator 插件。
853870

@@ -1124,18 +1141,17 @@ AS 已帮你集成了一些注释模板，我们只需要直接使用即可，
11241141

11251142
| 名称 | 缩写 |
11261143
| -------------------- | ---------------------------------------- |
1127-
| icon | ic（主要用在 App 的图标） |
1128-
| color | cl（主要用于颜色值） |
11291144
| average | avg |
11301145
| background | bg（主要用于布局和子布局的背景） |
1131-
| selector | sel（主要用于某一 view 多种状态，不仅包括 ListView 中的 selector，还包括按钮的 selector） |
11321146
| buffer | buf |
11331147
| control | ctrl |
1148+
| current | cur |
11341149
| default | def |
11351150
| delete | del |
11361151
| document | doc |
11371152
| error | err |
11381153
| escape | esc |
1154+
| icon | ic（主要用在 App 的图标） |
11391155
| increment | inc |
11401156
| infomation | info |
11411157
| initial | init |
@@ -1146,10 +1162,12 @@ AS 已帮你集成了一些注释模板，我们只需要直接使用即可，
11461162
| message | msg |
11471163
| password | pwd |
11481164
| position | pos |
1165+
| previous | pre |
1166+
| selector | sel（主要用于某一 view 多种状态，不仅包括 ListView 中的 selector，还包括按钮的 selector） |
11491167
| server | srv |
11501168
| string | str |
1151-
| temp | tmp |
1152-
| window | wnd |
1169+
| temporary | tmp |
1170+
| window | wnd（win） |
11531171

11541172
程序中使用单词缩写原则：不要用缩写，除非该缩写是约定俗成的。
11551173

@@ -1209,7 +1227,7 @@ AS 已帮你集成了一些注释模板，我们只需要直接使用即可，
12091227
[Android 包命名规范]: http://www.ayqy.net/blog/android%E5%8C%85%E5%91%BD%E5%90%8D%E8%A7%84%E8%8C%83/
12101228
[Android 开发最佳实践]: https://github.com/futurice/android-best-practices/blob/master/translations/Chinese/README.cn.md
12111229
[Android 编码规范]: http://www.jianshu.com/p/0a984f999592
1212-
[阿里巴巴 Java 开发手册]: https://102.alibaba.com/newsInfo.htm?newsId=6
1230+
[阿里巴巴 Java 开发手册]: https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E7%BA%AA%E5%BF%B5%E7%89%88%EF%BC%89.pdf
12131231
[Project and code style guidelines]: https://github.com/ribot/android-guidelines/blob/master/project_and_code_guidelines.md
12141232
[Google Java 编程风格指南]: http://www.hawstein.com/posts/google-java-style.html
12151233
[小细节，大用途，35 个 Java 代码性能优化总结！]: http://www.jianshu.com/p/436943216526

0 commit comments

Comments
 (0)