组队编码规范

之后的更新都在GitHub上进行，地址：编码规范——GitHub

历史变更：
2015.10.23

  • 添加与android studio相关的设置
  • 去掉编程实践章节
  • 优化排版，增加目录跳转
  • 增加部分Android命名约定

2015.10.03

  • 预览版完成

目录

一、前言
二、源文件
三、格式
四、变量和数组
五、switch语句
六、注释风格
七、命名约定

一、前言

注：修改的部分基本上都在 Settings -> Editor -> Code Style -> Java 里面。除非特别说明，以下"在xx选项卡下“均默认读者已经打开到这个界面。

  • 适用范围：本次软件工程课程的编程。

二、源文件

1 文件编码

文件编码统一为UTF-8。

Android Studio编码设置方法：Settings -> Editor -> File Encodings

  • IDE Encoding 设为UTF-8
  • Project Encoding 设为UTF-8
  • Properties Files 设为UTF-8，后面勾勾上。

2 源文件结构

一个源文件包含(按顺序地)：

  1. package语句
  2. import语句
  3. 该类的主要功能说明
  4. 一个顶级类
一个文件内不能：
public class ClassA{
}

public class ClassB{
}
即最外层的类只能有一个

注：以上每个部分之间用一个空行隔开。

2.1 package语句

  • 每个package语句独立放一行，语句再长也不换行。

按照Android Studio默认的设置即可。

2.2 import语句

  • 同上，每个语句独立一行。
  • 不能使用通配符，如import java.util.*; 。
  • import的顺序和间距，按照Android Studio默认的设置即可。

2.3 该类的主要功能说明

  • 在类的开头，添加该类功能的简要说明。
    使用以下样式：

    /**
  * 在这里写上功能说明
  */

2.4 类声明

  • 只能有一个顶级类。顶级类的名字和它所在的源文件同名（不含.java）
  • 类成员按照某种逻辑排序，维护者应该要能解释这种排序逻辑。

比如，新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。

  • 当一个类有多个构造函数，或者有多个同名方法（重载），这些函数/方法应该按顺序出现在一起，中间不要放进其他函数/方法。

三、格式

术语说明：块状结构(block-like construct)指的是一个类，方法或构造函数的主体。
示例代码：

if (state == true) {
    num++;
} else { }

3.1 大括号

大括号与if, else, for, do, while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上。

在Wrapping and Braces选项卡下
'if()'statement
'for()'statement
'while()'statement
'do()'statement
的Force Braces一项，选择Always。

3.2 非空块

  • 见示例代码的if块：左右大括号与代码放在一行。

在Wrapping and Braces选项卡的Braces placement下所有选项都选择End of line。

3.3 空块

  • 见示例代码的else块：else后的大括号内没有内容，则简洁地写成{ }

在Wrapping and Braces选项卡的Keep when reformatting下Simple blocks in one line后勾选。
此处有问题，需要手动写成{ }。无法通过代码格式化将两个不在同一行的括号自动放在同一行。包括它本身的含义，单语句块也无法自动简化为一行。目测是个BUG。

3.4 块缩进

  • 见示例代码的if块：缩进增加4个空格。

在Tabs and Indents选项卡下：
Tab size: 4
Indent: 4
Continuation indent: 8

3.5 语句行

  • 每个语句后要换行。
    例如，不能出现以下情况：

    int apple = 1; int pie = 1;

    无论语句多简单，都要换行。

3.6 自动换行

  • 一般情况下，一行长代码为了避免超出列限制而被分为多行，称之为自动换行(line-wrapping)。

  • 可以通过合理缩短方法或局部变量的长度来解决代码过长的问题。

  • 自动换行的基本准则：更倾向于在更高的语法级别处断开。

    • 如果在非赋值运算符处断开，那么在该符号前断开(比如+，它将位于下一行)。这条规则也适用于以下类运算符符号：点分隔符“.”和catch块中的管道符号“catch (FooException | BarException e)”。
    • 如果在赋值运算符处断开，通常的做法是在该符号后断开(比如=，它与前面的内容留在同一行)。这条规则也适用于foreach语句中的分号。
    • 逗号(,)与其前面的内容留在同一行。

  • 自动换行时额外再缩进4个空格。

3.7 列限制

  • 列限制为100个字符。

    除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。

    • package和import语句。
    • 注释中那些可能被剪切并粘贴到shell中的命令行。

3.8 空白

  • 垂直空白
    以下情况需要使用一个空行：

    • 类内连续的成员之间，如连续的字段，构造函数，方法，嵌套类，静态初始化块，实例初始化块。

      例外：两个连续字段之间的空行是可选的，用于字段的空行主要用来对字段进行逻辑分组。

    • 在函数体内，语句的逻辑分组间使用空行。

    • 类内的第一个成员前或最后一个成员后不为空行。

  • 水平空白
    按照Android Studio默认设置。

3.9 水平对齐

术语说明：水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。(一般是在使用“//”注释的时候)

  • 水平对齐不作要求。

    对齐可增加代码可读性，但它为日后的维护带来问题。
    考虑未来某个时候，我们需要修改一堆对齐的代码中的一行。 这可能导致原本很漂亮的对齐代码变得错位。很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐(比如程序员想保持这种水平对齐的风格)， 这就会让你做许多的无用功，增加了reviewer的工作并且可能导致更多的合并冲突。

3.10 用小括号来限定组

  • 我们没有理由假设读者能记住整个Java运算符优先级表。除非作者和reviewer都认为去掉小括号也不会使代码被误解，或是去掉小括号能让代码更易于阅读，否则我们不应该去掉小括号。

四、变量和数组

4.1 变量声明

  • 每次只声明一个变量。不要使用组合声明。
    int a, b;是不被允许的。
    应该：

    int a;  
int b;

  • 需要时才声明，并尽快进行初始化。

    • 不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明。
    • 局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化。

4.2 数组

  • 数组声明
    中括号是类型的一部分：String[] args， 而非String args[]。

  • 数组初始化可以写成块状结构。
    可以有多种写法，但这里推荐：

    int[] integers = new int[]{
        0, 1, 2, 3
};

五、switch语句

5.1 缩进

  • 内容缩进为增加4个空格。
  • 每个switch标签后新起一行，再缩进4个空格，写下一条或多条语句。

5.2 default

  • 每个switch语句都应包含一个default语句组，即使它不包含任何代码。

六、注释风格

块注释与其周围的代码在同一缩进级别。它们可以是/* ... */风格，也可以是// ...风格。对于多行的/* ... */注释，后续行必须从*开始， 并且与前一行的*对齐。以下示例注释都是OK的。

/*
 * This is          // And so           /* Or you can  	
 * okay.            // is this.          * even do this.   	 
 */                                      */

七、命名约定

这里用到的四种主要的标识符命名法：

  • 大驼峰命名法：每个单词首字母为大写
  • 小驼峰命名法：第一个单词全小写，其余单词首字母大写
  • 下划线命名法：每个单词之间用下划线作为间隔
  • 匈牙利命名法：变量名 = 属性_类型_对象描述

7.1 标识符类型的命名约定

  • 包名
    全部小写，连续的单词只是简单地连接起来，不使用下划线。

  • 类名
    使用大驼峰命名法。

类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语。

  • 方法名
    使用小驼峰命名法。

方法名通常是动词或动词短语。

  • 常量名
    使用下划线命名法，且常量名全部字母大写。

  • 非常量字段名、参数名、局部变量名
    使用小驼峰命名法。

非常量字段名通常是名词或名词短语。

7.2 Android命名约定

以上的命名约定并不能满足Android的使用范围，故另外添加Android需要用到的命名约定。

  • 类名

    |类|添加后缀|
    |:--|:--|
    |Activity类|Activity|
    |Adapter类|Adapte|
    |BroadcastReceive类|Broadcast|
    |ContentProvider|Provider|
    |Service类|Service|
    |公共方法类|Tools或Manager|
    |解析类|Hlr|
    |数据库类|DBHelper|
    |直接写的共享基础类|Base（应为前缀）|

  • 方法名

方法 说明
clearXX() 清空全部数据
displayXX() 弹出提示框和提示信息
drawXXX() 绘制数据或效果
getXX() 返回某个值的方法
initXX() 初始化
isXX() 返回值为boolean型
processXX() 对数据进行处理
removeXXX() 清除某一数据
resetXX() 数据重组
saveXX() 保存数据
  • 变量名后缀
量词 解释
First 第一个变量
Last 最后一个变量
Next 下一个变量
Prev 上一个变量
Cur 当前变量
  • 布局文件中控件id命名
    id命名格式为：控件名缩写_逻辑名称
控件名称 控件名缩写
视图
AutoCompleteTextView autoTv
ExpandableListView expLv
ImageView imgv
LayoutView lov
ListView lv
MapView mapv
RelativeView rv
ScollView sv
TextView tv
VideoView vdov
WebView webv
按钮
Button btn
ImageButton imgBtn
RadioButton rdoBtn
ToggleButton tglBtn
条
ProgressBar proBar
RantingBar ratBar
SeekBar skBar
时间
AnalogClock anaClk
DigtalClock dgtClk
DatePicker dtPk
TimePicker tmPk
Chronometer cmt
切换
TextSwitch txSwch
ImageSwitch imgSwch
Spinner spn
Tab tab
其他
ZoomControls zmCtl
CheckBox chk
EditText edtTx

  • 资源文件
    按照这样的格式：控件缩写_功能[_状态]

  • 常用单词缩写

    |单词|缩写|
    |:--|:--|
    |average|avg|
    |background|bg|
    |buffer|buf|
    |color|cl|
    |control|ctrl|
    |delete|del|
    |divider|di|
    |document|doc|
    |error|err|
    |escape|esc|
    |icon|ic|
    |image|img|
    |increment|inc|
    |infomation|info|
    |initial|init|
    |length|len|
    |library|lib|
    |message|msg|
    |password|pwd|
    |position|pos|
    |selector|sl|
    |server|srv|
    |string|str|
    |temp|tmp|
    |window|win|

posted @ 2015-10-03 19:43  schaepher  阅读(673)  评论(2)  编辑  收藏  举报