02-code-guideline.md

编码指南及规范

2021-04-15 @xinggang

参考：《阿里巴巴Java开发手册_1.7.0_嵩山版.pdf》、Github

一、开发指南

内容待完善...

二、注释规范

1、文件注释

每个代码文件都必须有文件注释，标准注释示例如下，其中必须包含的内容有：文件名称及作用、作者、创建日期，示例如下：

/**
 * 用户管理服务类
 * 
 * @auther xinggang
 * @create 2021-04-10
 * @modify 2021-04-15，xinggang，重构了用户验证逻辑。
 */
public class UserService {
    
}

以上为 java 语法，Kotlin 文件注释完全相同。

主要节点说明：

• 文件名称：必须，文件名称及可选的详细注释，支持加粗、换行等，若文件功能相对复杂尽量详细编写。
• @author：必须，内置语法，标示作者，可用自己的中文姓名或拼音。
• @create：必须，非内置语法，用于标示文件创建日期。
• @modify：可选，非内置语法，用于记录文件修改日志，每次有大的改动时新增一行。

可选节点说明：

• @see：增加链接。
• @since：从哪个版本开始。
• @version：版本号。

扩展语法：

Java：支持简单的 html 语法

<h2>    标题
<p>     段落
<br>    换行
<code>  代码

Kotlin：支持简单的 Markdown 语法

##      二级标题

关于换行：Java 中换行请使用 <br> 或 <p> 标签，Kotlin 中换行直接留一空白行。

IDEA 文件模板：

在 IDEA 中新建文件时可自动生成注释模板，模板内容如下：

设置路径：File | Settings | Editor | File and Code Templates

/**
 * 文件名称及作用
 * 
 * @author 您的姓名
 * @create ${YEAR}-${MONTH}-${DAY}
 */

2、方法注释

方法注释必须编写方法名(或者作用)，对于参数一目了然的方法可以省略参数注释，返回值注释也一样可选。

/**
 * 根据用户 id 获取图片输入流
 * @param id 用户ID
 */
private InputStream getImage(String id){
    //这里是代码
}

3、代码行注释

方法内的代码直接使用行注释即可：

//这里是注释
String str="hello world";

三、命名规范

内容待完善...

四、Git 仓库

内容待完善...