前言

为了规范开发明确团队相互之间的协作对于目前一些基本定义达成一致标准，尝试制定一些约定。

代码注释约定(C++、Go、JS)

采用统一的标准代码注释约定:

带参数方法的注释

/**
 * 方法注释
 * @param a 参数说明
 * @return 返回值说明
 **/
bool func(int a);

无参数方法的注释

/**
 * 方法注释
 **/
void func();

变量说明

/**
 * 变量注释
 **/
int a;

命名约定

方法名约定

单一约定

名称	方法名约定
新增	create
添加	add
删除	remove
修改	update
查询(单个结果)	get
查询(多个结果)	list
分页查询	page
统计	total

对仗约定

名称	方法名约定
新增/删除	add/remove
初始化/释放	init/freed
递增/递减	increment/decrement
打开/关闭	open/close
开始/结束	begin/end
插入/删除(位置)	insert/delete
显示/隐藏	show/hide
创建/释放	create/destroy
锁/解锁	lock/unlock
来源/目标(资源)	source/target
最前/最后(列表)	first/last
最小/最大	min/max
获取/设置	get/set
往后(下一个)/往前(上一个)	next/previous
向上/向下	up/down
旧/新	old/new

日志规范

日志规范分别为: ERROR、WARN、INFO、DEBUG

ERROR 级别

ERROR 表示不能自动修复的错误信息，需要立即被关注和解决。例如:数据库错误，I/O 错误等。ERROR 的错误信息需要接入报警系统，需要立刻人工介入，及时解决防止线上出问题。

WARN 级别

WARN 表示可以自动修复的错误或已知业务问题，为了避免已知的问题进入报警系统采用 WARN 级别的日志。例如:参数校验不通过，没有权限访问业务等。需要注意！！在短时间内产生过多的 WARN 日志，也是一种缺陷，所以最好的方式是设置一个 WARN 的阈值，达到后进行报警。

INFO 级别

INFO 表示记录系统的基本运行过程和运行状态，但切忌不能过度使用 INFO，把 INFO 当做 DEBUG 级别的日志使用。

DEBUG 级别

DEBUG 表示输出的调试信息，用作在定位问题时需要判断出问题的地方，如:request/response 的对象内容。通常在开发和预发环境下，DEBUG 日志会打开，以方便开发和调试。而线上环境，DEBUG 开关需要被关闭，防止生产环境的日志量过大，避免不必要的服务器的损耗。如果在线上环境遇到问题需要 DEBUG 日志。可以选择动态开启一段时间收集 DEBUG 日志，但是一定要记得关闭！！！

软件工程协定规范

前言