什么是好的代码？

  • 满足业务需要：代码是来实现业务的，如果业务都实现不了，代码也就没什么价值了
  • 代码尽可能的清晰明了：就是让小白也能看懂你的代码
  • 代码尽可能的少：在保证清晰明了的前提下，能少一行少一行，能少一个类少一个类，能少一行注释少一行注释
  • 代码尽可能复用性和模块化：在保证清晰明了和尽可能少的前提下，能复用的代码尽量复用，能模块的尽量模块

英文单词命名规范

无论前端代码还是后端代码，都是由一个个单词组成的，所以好的命名规范至关重要：

1）合理使用正确的英文单词

  • 一定要用英文，且单词正确，不要用汉语拼音；

  • 英文单词一定要使用常用词；

  • 英文单词要符合业务；

2）合理区分名词和动词

  • 项目名、类名、数据库名、表名应该用名词，比如： OrderService。

  • 具体的方法名应该是 动词 或 动名词，比如：创建订单 createOrder，查询订单 queryOrder。

3）各个端、数据库、等命名要统一

前端、后端、移动端、数据库、服务器对某个业务或者某个业务单元的命名必须保持一致。

1
2
3
4
5
比如 `通知` 功能，各个端定义为：   
- 后端: `notice`, （NoticeController, 表：t_notice）
- 前端写成 `news`， （news-list.vue， /news/news-list）
- 移动端写成 `message`，(MessageFragement)
- 最后再对接的时候，懵逼了，懵了；

注释规范

1）注释和代码一样重要

注释除了说明作用、逻辑之外。还有一个很重要的原因：当业务逻辑过于复杂，代码过于庞大的时候，它能有效得帮助我们免于陷入代码与业务逻辑的泥沼之中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/**
* 开始抽奖方法
* 保存中奖信息、奖励用户积分等
* @param luckDrawDTO
* @return ResponseDTO 返回中奖信息
*/
public ResponseDTO<String> startLuckDraw(LuckDrawDTO luckDrawDTO) {

    // -------------- 1、校验抽奖活动基本信息 ----------------------
    xxx 伪代码一顿操作

    // -------------- 2、新增抽奖记录 -----------------------------
    xxx 伪代码一顿操作

    // -------------- 3、如果需要消耗积分，则扣除钢镚积分 -------------
    xxx 伪代码一顿操作

    // -------------- 4、获取奖品信息，开始翻滚吧 --------------------
    xxx 伪代码一顿操作

    return ResponseDTO.succ(luckDrawPrizeVO);
}

2）注释和代码的一致性

注释并不是越多越好，当注释过多，维护代码的同时，还需要维护注释，不仅变成了一种负担，也与我们当初添加注释的初衷背道而驰。

  • 需要的时候，才辅以注释说明。注释内容要简洁、明了、无二义性，信息全面且不冗余。

  • 无论是修改、复制代码时，都要仔细核对注释内容是否正确。

3）方法注释

方法要尽量通过方法名自解释，不要写无用、信息冗余的方法头，不要写空有格式的方法头注释。

方法头注释内容可选，但不限于：功能说明、返回值，用法、算法实现等等。尤其是对外的方法接口声明，其注释，应当将重要、有用的信息表达清楚。

1
2
3
4
5
6
7
8
/**
 * 解析转换时间字符串为 LocalDate 时间类
 * 调用前必须校验字符串格式 否则可能造成解析失败的错误异常
 *
 * @param dateStr 必须是 yyyy-MM-dd 格式的字符串
 * @return LocalDate
 */
public static LocalDate parseYMD(String dateStr){}

TODO FIX 规范

TODO/TBD(to be determined) 注释一般用来描述已知待改进、待补充的修改点,并且加上作者名称。
FIXME 注释一般用来描述已知缺陷，它们都应该有统一风格，方便文本搜索统一处理。如：

1
2
// TODO <author-name>: 补充 XX 处理
// FIXME <author-name>: XX 缺陷

无用代码：删

因为现在所有的项目都使用了代码管理工具，比如 git、svn 、ts 等等，所以对于无用的代码，让我们尽情的删除掉吧！重要的说三遍：不要注释，不要注释，不要注释！要删除代码，要删除代码，要删除代码！

代码 Git 提交规范

  • 提交前应该冷静、仔细检查一下，确保没有忘记加入版本控制或不应该提交的文件。

  • 提交前应该先编译一次，防止出现编译都报错的情况。

  • 提交前先更新 pull 一次代码，提交前发生冲突要比提交后发生冲突容易解决的多。

  • 提交前检查代码是否格式化，是否符合代码规范，无用的包引入、变量是否清除等等。

  • 提交时检查注释是否准确简洁的表达出了本次提交的内容。

  • 提交代码时必须填写详细备注，如完成功能，注释为 “新增 XX 功能”；

  • 若此次提交代码对应禅道中的任务或者 bug，格式如下：

1
2
task#[任务 id] [任务标题] [具体事项]
bug#[bug id] [bug标题] [具体事项]

  • 例子如下：

1
2
git commit -m 'task#1101 开发订单功能 完成订单创建编码'
git commit -m 'bug#1102 时间格式错误 订单时间格式'

保持项目整洁

使用 git，必须添加 .gitignore 忽略配置文件。不要提交与项目无关的内容文件：idea 配置、target 包等。