java 编码规范

1 介绍

本规范参考java 官方编码规范,简化而来,更详细的介绍请参考Code Conventions for the Java TM Programming Language
本规范适用但不限于OS Lite项目使用。

2 文件名

这项目组列出了常用的文件名及其后缀。

2.1 文件后缀

Java程序应用下列文件后缀:

文件类别 文件后缀
Java源文件 .java
Java字节码文件 .class

2.2 常用文件

常用的文件名包含:

文件名 用处
README.md 大的独立模块下用来说明该模块打使用注意事项等

3 文件组织

一个文件由被空行分隔而成的段落以及标识每个段落的注释共同构成。超过2000行的程序难以浏览,应当尽量避免。

3.1 Java源文件

若private类或interface与一个public类关系紧密,可以将它们放入同一个源文件,但是public类必须是这个文件中的第一个类或接口。

Java源文件应遵守以下规范:

  • 开首注释
  • 包和引入语句
  • 类和接口声明

3.1.1 文件头注释

为了方便生成api ref,所有的源文件都应当有文件头注释例如:

1
2
3
4
5
6
7
/**
* Version information
*
* Date
*
* Copyright notice
*/

3.1.2 包和引入语句

在多半Java源文件中,第一个非注释行是包语句。在它之后可以跟引入语句

1
2
3
package com.turing123.robotframe;

import android.content.Context;

3.1.3 类和接口声明

下表描述了类和接口声明

序号 类/接口声明的各项目 注解
1 类/接口文档注释(/*……/) 该注释中所需包含的信息,拜见”文档注释”
2 类或接口的声明
3 类的(静态)变量 开头是类的公共常量,最后是私有常量。
4 实例变量 同上
5 构造方法
6 成员方法 这些方法应当按功能分组。例如,一个私有的类方法可以置于两个公有的实例方法之间。其目标是为了更便于浏览代码。

4 缩进排版

4个空格作为缩进排版的一个单位。

4.1 行长度

尽量避免一行的长度跨越100个字符。

4.2 换行

当一个表达式无法容纳在一行内时,可以根据如下规则断开之:

  • 在一个逗号后面断开
  • 在一个操纵符前面断开
  • 新的一行应当与上一行同一级别表达式的开首处对齐
1
2
public void prepare(@NonNull MessageInterceptor interceptor,
@NonNull final RobotFramePreparedListener listener)

if语句的换行,例如:

1
2
3
4
5
6
if (behaviors == null
|| behaviors.behaviors == null
|| behaviors.behaviors.size() == 0) {

//do something
}

三元运算表达式打换行,例如:

1
2
3
4
5
alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression)?
beta
: gamma;

5 注释

5.1 注释的格式

程序可以有4种实现注释的风格:块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。

5.1.1 块注释

块注释每个文件的开端处以及每个方法之前。它们也可以被用于方法内部。在功能和方法内部的块注释应当和它们所描述的代码具有一样的缩进格局。

块注释可以以/**开头

1
2
3
4
5
6
/**
* Set NLP Sever's ApiKey and Secret.
*
* @param apiKey Your ApiKey.
* @param secret Your Secret.
*/

5.1.2 单行注释

短注释可以显示在一行内,单行注释之前应当有一个空行。

1
2
3
4
5
if (condition) {

/* Handle thecondition. */
...
}

5.1.4 行末注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
if (foo > 1) {

// Do adouble-flip.
...
}
else {
return false; // Explain why here.
}

//if (bar > 1){
//
// // Do a triple-flip.
// ...
//}
//else {
// return false;
//}

5.2 文档注释

文档注释描述Java的类、接口、方法以及字段(field)。每个文档注释都邑被置于注释定界符/*…/之中,一个注释对应一个类、接口或成员。该注释应位于声明之前,该注释将被用来生成javadoc api ref.

1
2
3
4
5
6
7
8
9
10
/**
* Provide ASR function
*/
public final class ASR extends FunctionBase{
/**
* Chat Mode: CHAT_MODE_AUTO
* Robot framework's chat will auto running, you needn't care about asr and ask the cloud.
*/
public static final int CHAT_MODE_AUTO = 0;
}

6 声明

6.1 每行声明变量的数量

推荐一行一个声明,因为这样利于写注释

1
2
int level;  // indentation level
int size; // size of table

6.2 初始化

尽量在声明局部变量的同时初始化

6.3 布局

只在代码块的开端处声明变量,不要在初次用到该变量时才声明它。

1
2
3
4
5
6
7
8
void myMethod() {
int int1 = 0; // beginning of method block

if (condition) {
int int2 = 0; // beginning of "if"block
...
}
}

6.4 类和接口的声明

当编写类和接口是,应当遵守以下格局规范:

  • 在方法名与其参数列表之前的左括号”(”间不要有空格
  • 左大括号”{“位于声明语句同业的末尾
  • 右大括号”}”另起一行,与响应的声明语句对齐,除非是一个空语句,”}”应紧跟在”{“之后
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    public class Behavior {
    public String exception;
    public IntentInfo intent;
    public Recommend recommend;
    public List<ResponseResult> results;
    public List<Sequence> sequences;
    public Emotion emotion;

    public Behavior() {
    }

    public Behavior(String exception) {
    this.exception = exception;
    }

    public Behavior(String exception, IntentInfo intent, Recommend recommend,
    List<ResponseResult> results, List<Sequence> sequences,
    Emotion emotion) {
    this.exception = exception;
    this.intent = intent;
    this.recommend = recommend;
    this.results = results;
    this.sequences = sequences;
    this.emotion = emotion;
    }
    }

7 语句

7.1 简单语句

1
2
3
argv++;       // Correct
argc--; // Correct
argv++; argc--; // AVOID!

7.2 复合语句

  • 被括此中的语句应当较之复合语句缩进一个层次
  • 左大括号”{“应位于复合语句开端行的行尾;右大括号”}”应另起一行并与复合语句首行对齐。

7.3 返回语句

一个带返回值的return语句不应用小括号”()”

7.4 if,if-else,if else-if else语句(if, if-else, if else-if elseStatements)

if-else语句应当具有如下格示:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
if (condition) {
statements;
}

if (condition) {
statements;
} else {
statements;
}

if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}

7.5 for语句

一个for语句应当具有如下格示:

1
2
3
for (initialization; condition; ) {
statements;
}

一个空的for语句应当具有如下格示:

1
for (initialization; condition; );

7.6 while语句

一个while语句应当具有如下格示:

1
2
3
while (condition) {
statements;
}

一个空的while语句应当具有如下格示:

1
while (condition);

7.7 do-while语句

一个do-while语句应当具有如下格示:

1
2
3
do {
statements;
} while (condition);

7.8 switch语句

一个switch语句应当具有如下格示:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;

case XYZ:
statements;
break;

default:
statements;
break;
}

7.9 try-catch语句

一个try-catch语句应当具有如下格示:

1
2
3
4
5
try {
statements;
} catch (ExceptionClass e) {
statements;
}

1
2
3
4
5
6
7
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}

8 空白

8.1 空行

空行将逻辑相干的代码段分隔开。

下列景象应当是应用两个空行:

  • 一个源文件的两个片段(section)之间
  • 类声明和接口声明之间

下列景象应当是应用一个空行:

  • 两个方法之间
  • 方法内的局部变量和方法的第一条语句之间

8.2 空格

下列情况当应用空格:
一个紧跟着括号的关键字应当被空格分隔,例如:

1
2
3
whiletrue) {
...
}

注意:空格不该该置于法名与其左括号之间。这将有助于区分关键字和方法调用。

  • 空白应当位于参数列表中逗号的后面
  • 所有的二元运算符,除了”.”,应当应用空格将之与操纵数分隔。一元操纵符和操纵数之间不因该加空格,比如:负号(”-“)、自增(”++”)和自减(”–”)。例如:

9 命名规范

标识符类型 命名规范 例子
一个独一包名的前缀老是全部小写的ASCII字母并且是一个域名,这类命名规范可能以特定目次名的构成来区分部 门(department),项目(project)。 com.turing123.robotframe
命名规范:类名是个一名词,采取大小写混淆的体式格式,每个单词的首字母大写。尽量使你的类名简洁而富于描述。应用完全单词,避免缩写词 class Behavior
接口 命名规范:大小写规范与类名类似 interface IASRCallback
方法 方法名是一个动词,采取大小写混淆的体式格式,第一个单词的首字母小写,其后单词的首字母大写。 void onStartRecord()
变量 除了变量名外,所有实例,包含类,类常量,均采取大小写混淆的体式格式,第一个单词的首字母小写,其后单词的首字母大写。变量名不该以下划线或美元符号开首,尽管这在语法上是容许的。变量名应简短且富于描述。变量名的选用应当易于记忆,即,可以或许指出其用处。尽量避免单个字符的变量名,除非是一次性的姑且变量。姑且变量凡是被取名为i,j,k,m和n,它们一般用于整型;c,d,e,它们一般用于字符型。 char c;
实例变量 大小写规范和变量名类似
常量 类常量应当全部大写,单词间用下划线隔开 public static final int CHAT_MODE_AUTO = 0

10 Java源文件示例

下面的例子,显示了一公共类的Java源程序(仅作为示例)。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
package com.turing123.robotframe;

import android.content.Context;
/**
* <p>
* The entry to use RobotFrame.<br/><br/>
* Usage:<br/>
* The method <font color="blue">prepare</font> must be called prior to any method calling on this frame.
* The normal steps to use this frame are as blow:<br/>
* 1. call <font color="blue">getInstance()</font><br/>
* 2. call <font color="blue">prepare(prepareListener)</font><br/>
* 3. waiting for prepareListener callback<br/>
* 4.1 if success, call <font color="blue">start()</font> to launch the robot up<br/>
* 4.2 if error occurred, check and fix the issue according to error message<br/>
* 5. if robot is attempting to shutdown, call method <font color="blue">shutDown(shutdownListener)</font>
* first and wait until the shutdownListener called back.<br/>
* <p>
* <strong><font color="red">WARNING: Any violation from the steps above will cause unpredictable
* behaviors.</font></strong>
*/

public class RobotFrameManager {
/**
* Chat Mode: CHAT_MODE_AUTO
* Robot framework's chat will auto running, you needn't care about asr and ask the cloud.
*/
public static final int CHAT_MODE_AUTO = 0;
/**
* Chat Mode: CHAT_MODE_MANUAL
* Robot framework‘s Chat requires manual call ASR and ask the cloud.
* In this mode, the output mode only is {@link #OUTPUT_MODE_ASSEMBLE}
*/
public static final int CHAT_MODE_MANUAL = 1;

private static RobotFrameManager mInstance = null;

private FrameService mService;
private Context mContext;

public RobotFrameManager(Context context) {
mContext = context;

SystemProperties.getInstance().init(context);

mService = new FrameService(context);

PluginService.setUp(mContext);
}

/**
* Be RobotFrame prepared, must be called prior to any calling to other method
*
* @param states the Frame working mode and states(if has)
* @param listener the callback listener
*/
public void prepare(int states, @NonNull final RobotFramePreparedListener listener) {
mService.prepare(states,listener);
}

/**
* The robot starting run
*/
public void start() throws IllegalStateException {
mService.start();
}

/**
* Set NLP Sever's ApiKey and Secret.
*
* @param apiKey Your ApiKey.
* @param secret Your Secret.
*/
public void setApiKeyAndSecret(String apiKey, String secret) {
Preconditions.checkNotNull(apiKey, true);
Preconditions.checkNotNull(secret, true);

Settings.init(mContext);
Settings.put(SettingsKey.TURING_APIKEY, apiKey);
Settings.put(SettingsKey.TURING_SECRET, secret);
Settings.deInit();
}
}
robot wechat
欢迎您扫一扫上面的微信公众号,订阅我的博客!
坚持原创技术分享,您的支持将鼓励我继续创作!