Department Coding Guidelines

iOS and C++ Coding Guidelines

Posted by Haoking on December 13, 2018

Please indicate the source of forwarding and be a follower of my Github.

Coding Guidelines

Department Coding Guidelines

This is the coding guidelines for our department.




GIARAN编程规约 
目录


()	         ...................................................................1
()	         ...................................................................3
()	         ...................................................................4
()	OOP 规约		  ...................................................................6
()	         ...................................................................9
()	         ..................................................................12
()	         ..................................................................14
()	         ..................................................................16
()	            ..................................................................17




 
开发手册


版本号	
制定团队	
更新日期	
备注
1.0.0	
GIARAN技术团队	2018.0125	待修订

() 命名风格
1.	强制代码中的命名均不能以下划线或美元符号开始也不能以下划线或美元符号结束  _name / name / $Object / name_ / name$ / Object$
2.	强制类名使用 UpperCamelCase 风格必须遵从驼峰形式
  MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
  macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
3.	强制方法名参数名成员变量局部变量都统一使用 lowerCamelCase 风格必须遵从驼峰形式
   localValue / getHttpMessage() / inputUserId
4.	强制常量命名全部大写单词间用下划线隔开力求语义表达完整清楚不要嫌名字长正例MAX_STOCK_COUNT
反例MAX_COUNT
5.	强制抽象类命名使用 Abstract  Base 开头异常类命名使用 Exception 结尾测试类命名以它要测试的类的名称开始 Test 结尾
6.	强制布尔类型的变量都不要加 is否则部分框架解析会引起序列化错误反例定义为基本数据类型 Boolean isDeleted的属性它的方法也是 isDeleted()RPC
 
框架在反向解析的时候"以为"对应的属性名称是 deleted导致属性获取不到进而抛出异常
7.	强制库类公共API, 变量命名规则, "Giaran"+"模块名称"+"变量名"
正例GiaranLandmarkPoint
反例Point
8.	强制库类公共API, 方法命名规则标准库只显式的展示公共方法私有的方法和变量放在内部类中最好提供不同版本的API调用文件C++, Android, Java, JavaScript, 视情况而定
9.	推荐为了达到代码自解释的目标任何自定义编程元素在命名时使用尽量完整的单词组合来表达其意
正例从远程仓库拉取代码的类命名为 PullCodeFromRemoteRepository反例变量 int a; 的随意命名方式
10.	推荐如果模块接口方法使用了设计模式在命名时体现出具体模式说明将设计模式体现在名字中有利于阅读者快速理解架构设计理念
  public class OrderFactory; public class LoginProxy; public class ResourceObserver;

11.	参考枚举类名建议带上 Enum 后缀枚举成员名称需要全大写单词间用下划线隔开说明枚举其实就是特殊的常量类且构造方法被默认强制是私有
正例枚举名字为 ProcessStatusEnum 的成员名称SUCCESS / UNKOWN_REASON

 

() 常量定义
1.	强制不允许任何魔法值即未经定义的常量直接出现在代码中反例String key = "Id#Giaran_" + tradeId;
cache.put(key, value);
2.	推荐不要使用一个常量类维护所有常量按常量功能进行归类分开维护
说明大而全的常量类非得使用查找功能才能定位到修改的常量不利于理解和维护正例缓存相关常量放在类 CacheConsts 系统配置相关常量放在类 ConfigConsts 
1	子工程内部共享常量即在当前子工程的 constant 目录下
2	包内共享常量即在当前包下单独的 constant 目录下
3	类内共享常量直接在类内部 private static final 定义
3.	推荐如果变量值仅在一个范围内变化且带有名称之外的延伸属性定义为枚举类下面正例中的数字就是延伸信息表示星期几
正例public Enum { MONDAY(1), TUESDAY(2), WEDNESDAY(3), THURSDAY(4), FRIDAY(5), SATURDAY(6), SUNDAY(7);}


() 代码格式
1.	强制大括号的使用约定如果是大括号内为空则简洁地写成{}即可不需要换行如果是非空代码块则
1	左大括号前不换行
2	左大括号后换行
3	右大括号前换行
4	右大括号后还有 else 等代码则不换行表示终止的右大括号后必须换行
2.	强制 左小括号和字符之间不出现空格同样右小括号和字符之间也不出现空格详见第 5 条下方正例提示
反例if (空格 a == b 空格)
3.	强制if/for/while/switch/do 等保留字与括号之间都必须加空格
4.	强制任何二目三目运算符的左右两边都需要加一个空格
说明运算符包括赋值运算符=逻辑运算符&&加减乘除符号等
5.	强制采用 4 个空格缩进禁止使用 tab 字符
说明如果使用 tab 缩进必须设置 1  tab  4 个空格不同编译器对tab的识别不同
正例 涉及 1-5 
public static void main(String[] args) {
// 缩进 4 个空格
String say = "hello";
// 运算符的左右必须有一个空格
int flag = 0;
// 关键词 if 与括号之间必须有一个空格,括号内的 f 与左括号,0 与右括号不需要空格
if (flag == 0) { System.out.println(say);
}

// 左大括号前加空格且不换行;左大括号后换行
if (flag == 1) { System.out.println("world");
// 右大括号前换行,右大括号后有 else,不用换行
} else {
System.out.println("ok");
// 在右大括号后直接结束,则必须换行
}
}

 

6.	强制注释的双斜线与注释内容之间有且仅有一个空格正例// 注释内容,注意在//和注释内容之间有一个空格。
7.	强制单行字符数限制不超过 120 超出需要换行换行时遵循如下原则
1	第二行相对第一行缩进 4 个空格从第三行开始不再继续缩进参考示例
2	运算符与下文一起换行
3	方法调用的点符号与下文一起换行
4	方法调用时多个参数需要换行时在逗号后进行
5	在括号前不要换行见反例正例
StringBuffer sb = new StringBuffer();
// 超过 120 个字符的情况下,换行缩进 4 个空格,点号和方法名称一起换行
sb.append("zi").append("xin")...
.append("huang")...
.append("huang")...
.append("huang");
反例
StringBuffer sb = new StringBuffer();
// 超过 120 个字符的情况下,不要在括号前换行
sb.append("zi").append("xin")...append ("huang");

// 参数很多的方法调用可能超过 120 个字符,不要在逗号前换行
method(args1, args2, args3, ...
, argsX);
8.	强制方法参数在定义和传入时多个参数逗号后边必须加空格正例下例中实参的"a",后边必须要有一个空格
method("a", "b", "c"); 
9.	推荐没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐正例
int a = 3; long b = 4L; float c = 5F;
StringBuffer sb = new StringBuffer();
说明增加 sb 这个变量如果需要对齐则给 abc 都要增加几个空格在变量比较多的情况下是一种累赘的事情
10.	推荐方法体内的执行语句组变量的定义语句组不同的业务逻辑之间或者不同的语义之间插入一个空行相同业务逻辑和语义之间不需要插入空行
说明没有必要插入多个空行进行隔开

() OOP 规约
1.	强制避免通过一个类的对象引用访问此类的静态变量或静态方法无谓增加编译器解析成本直接用类名来访问即可尽量使用类方法不需要创建实例不需要释放实例内存
2.	强制所有的覆写方法必须加@Override 注解
说明getObject() get0bject()的问题一个是字母的 O一个是数字的 0@Override可以准确判断是否覆盖成功另外如果在抽象类中对方法签名进行修改其实现类会马上编译报错
3.	强制尽量不用可变参数编程, 使用分离的多参数编程减少出错机会编译较快
正例public User getUsers(String obj1) {...}
		     public User getUsers(String obj1, String obj2) {...}
       public User getUsers(String obj1, String obj2, String obj3) {...}
4.	强制外部正在调用或者二方库依赖的接口不允许修改方法签名避免对接口调用方产生影响接口过时必须加@Deprecated 注解并清晰地说明采用的新接口或者新服务是什么
5.	强制不能使用过时的类或方法
6.	强制所有的相同类型的包装类对象之间值的比较全部使用 equals 方法比较
尽量使用构造方法进行计算而尽量少使用逻辑运算符
说明对于运算符在进行每次运算时会new新对象占用寄存器并不会复用多次循环中可能造成内存溢出的情况
 
7.	强制构造方法里面禁止加入任何业务逻辑如果有初始化逻辑请放在 init 方法中
8.	推荐当一个类有多个构造方法或者多个同名方法这些方法应该按顺序放置在一起 便于阅读
9.	推荐 类内方法定义顺序依次是公有方法或保护方法 > 私有方法 > getter/setter
方法
 
说明公有方法是类的调用者和维护者最关心的方法首屏展示最好保护方法虽然只是子类关心也可能是"模板设计模式"下的核心方法而私有方法外部一般不需要特别关心是一个黑盒实现因为承载的信息价值较低所有 getter/setter 方法放在类体最后
10.	推荐 getter/setter 方法中不要增加业务逻辑增加排查问题的难度
反例
public Integer getData() { if (true) {
return this.data + 100;
} else {
return this.data - 100;
}
}

11.	推荐循环体内字符串的连接方式使用 append 方法进行扩展
说明反编译出的字节码文件显示每次循环都会 new 出一个对象然后进行
+ 操作最后通过 toString 方法返回 String 对象造成内存资源浪费
反例
String str = "start";
for (int i = 0; i < 100; i++) { str = str + "hello";
}
12.	推荐final 可以声明类成员变量方法以及本地变量下列情况使用 final 关键字
1	不允许被继承的类String 
2	不允许修改引用的域对象POJO 类的域变量
3	不允许被重写的方法POJO 类的 setter 方法
4	不允许运行过程中重新赋值的局部变量
5	避免上下文重复使用一个变量使用 final 描述可以强制重新定义一个变量方便更好地进行重构
13.	推荐类成员与方法访问控制从严库的设计中访问控制是最重要的部分
1	如果不允许外部直接通过 new 来创建对象那么构造方法必须是 private
2	工具类不允许有 public  default 构造方法
3	类非 static 成员变量并且与子类共享必须是 protected
4	类非 static 成员变量并且仅在本类使用必须是 private
5	 static 成员变量如果仅在本类使用必须是 private
 
6	若是 static 成员变量必须考虑是否为 final
7	类成员方法只供类内部调用必须是 private
8	类成员方法只对继承类公开那么限制为 protected
说明任何类方法参数变量严控访问范围过于宽泛的访问范围不利于模块解耦思考如果是一个 private 的方法想删除就删除可是一个 public  service 方法或者一个 public 的成员变量删除一下不得手心冒点汗吗变量像自己的小孩尽量在自己的视线内变量作用域太大无限制的到处跑那么你会担心的



() 集合处理
1.	强制不要在 foreach 循环里进行元素的 remove/add 操作remove 元素如果并发操作需要对象加锁
2.	推荐集合或者素组初始化时需要显式地指定集合初始值大小暂时无法确定大小请设置为默认值 16.
说明由于集合和数组地城都是用hashMap的存储方式当resize时需要重建hash表的结构严重影响性能 
 
3.	参考利用 Set 元素唯一的特性可以快速对一个集合进行去重操作避免使用 List 
contains 方法进行遍历对比去重操作


() 并发处理
1.	强制获取单例对象需要保证线程安全其中的方法也要保证线程安全说明资源驱动类工具类单例工厂类都需要注意
2.	强制创建线程或线程池时请指定有意义的线程名称方便出错时回溯正例
public class TimerTaskThread extends Thread { public TimerTaskThread() {
super.setName("TimerTaskThread");
...
}
 
3.	强制高并发时同步调用应该去考量锁的性能损耗能用无锁数据结构就不要用锁能锁区块就不要锁整个方法体能用对象锁就不要用类锁
说明尽可能使加锁的代码块工作量尽可能的小避免在锁代码块中调用 RPC 方法
4.	强制对多个资源数据库表对象同时加锁时需要保持一致的加锁顺序否则可能会造成死锁
说明线程一需要对表 ABC 依次全部加锁后才可以进行更新操作那么线程二的加锁顺序也必须是 ABC否则可能出现死锁
5.	强制并发修改同一记录时避免更新丢失需要加锁要么在应用层加锁要么在缓存加锁要么在数据库层使用乐观锁使用 version 作为更新依据
说明如果每次访问冲突概率小于 20%推荐使用乐观锁否则使用悲观锁乐观锁的重试次数不得小于 3  


() 控制语句
1.	强制在一个 switch 块内每个 case 要么通过 break/return 等来终止要么注释说明程序将继续执行到哪一个 case 为止在一个 switch 块内都必须包含一个 default 语句并且放在最后即使它什么代码也没有
2.	强制 if/else/for/while/do 语句中必须使用大括号即使只有一行代码避免采用单行的编码方式if (condition) statements;
3.	推荐表达异常的分支时少用 if-else 方式这种方式可以改写成
if (condition) {
...
return obj;
}
// 接着写 else 的业务逻辑代码;
说明如果非得使用 if()...else if()...else...方式表达逻辑,【强制避免后续代码维护困难请勿超过 3 
正例超过 3 层的 if-else 的逻辑判断代码可以使用卫语句策略模式状态模式等来实现
其中卫语句示例如下

public void today() { if (isBusy()) {
print("change time."); return;
}
if (isFree()) {
print("go to travel."); return;
}
 
print("stay at home to learn Alibaba Java Coding Guidelines."); return;
}

4.	推荐除常用方法 getXxx/isXxx等外不要在条件判断中执行其它复杂的语句将复杂逻辑判断的结果赋值给一个有意义的布尔变量名以提高可读性
说明很多 if 语句内的逻辑相当复杂阅读者需要分析条件表达式的最终结果才能明确什么样的条件执行什么样的语句那么如果阅读者分析逻辑表达式错误呢此外if的判断条件里的对象在if结束前是不释放的
正例
// 伪代码如下
final boolean existed = (file.open(fileName, "w") != null) && (...) || (...); if (existed) {
...
}
反例
if ((file.open(fileName, "w") != null) && (...) || (...)) {
...
}
5.	推荐循环体中的语句要考量性能以下操作尽量移至循环体外处理如定义对象变量获取数据库连接进行不必要的 try-catch 操作这个 try-catch 是否可以移至循环体外)。
6.	推荐接口入参保护这种场景常见的是用于做批量操作的接口
下列情形需要进行参数校验
1	调用频次低的方法
2	执行时间开销很大的方法此情形中参数校验时间几乎可以忽略不计但如果因为参数错误导致中间执行回退或者错误那得不偿失
3	需要极高稳定性和可用性的方法
4	对外提供的开放接口不管是 RPC/API/HTTP 接口
5	敏感权限入口
下列情形不需要进行参数校验
1	极有可能被循环调用的方法但在方法说明里必须注明外部参数检查要求
2	底层调用频度比较高的方法毕竟是像纯净水过滤的最后一道参数错误不太可能到底层才会暴露问题
3	被声明成 private 只会被自己代码所调用的方法如果能够确定调用方法的代码传入参
数已经做过检查或者肯定不会有问题此时可以不校验参数
 

() 注释规约
1.	强制类属性类方法的注释必须使用/**内容*/格式不得使用// xxx 方式。
2.	强制所有的类都必须添加创建者和创建日期
3.	强制方法内部单行注释在被注释语句上方另起一行使用//注释。方法内部多行注释使用/* */注释,注意与代码对齐。
4.	强制所有的枚举类型字段必须要有注释说明每个数据项的用途
5.	推荐代码修改的同时注释也要进行相应的修改尤其是参数返回值异常核心逻辑等的修改
说明代码与注释更新不同步就像路网与导航软件更新不同步一样如果导航软件严重滞后 就失去了导航的意义
6.	参考谨慎注释掉代码在上方详细说明而不是简单的注释掉如果无用则删除
说明代码被注释掉有两种可能性1后续会恢复此段代码逻辑2永久不用前者如果没有备注信息难以知晓注释动机后者建议直接删掉代码仓库保存了历史代码)。
7.	参考好的命名代码结构是自解释的注释力求精简准确表达到位避免出现注释的一个极端过多过滥的注释代码的逻辑一旦修改修改注释是相当大的负担
反例
// put elephant into fridge put(elephant, fridge);
 
方法名 put加上两个有意义的变量名 elephant  fridge已经说明了这是在干什么语义清晰的代码不需要额外的注释
8.	参考特殊注释标记请注明标记人与标记时间注意及时处理这些标记通过标记扫描 经常清理此类标记线上故障有时候就是来源于这些标记处的代码                                
   1 待办事宜TODO: 标记人标记时间[预计处理时间]
表示需要实现但目前还未实现的功能这实际上是一个 Javadoc 的标签目前的 Javadoc
还没有实现但已经被广泛使用只能应用于类接口和方法因为它是一个 Javadoc 标签)。
2 错误不能工作FIXME:标记人标记时间[预计处理时间]
在注释中用 FIXME 标记某代码是错误的而且不能工作需要及时纠正的情况


() 其它
1.	推荐不要在视图模板中加入任何复杂的逻辑
说明根据 MVC 理论视图的职责是展示不要抢模型和控制器的活
2.	推荐任何数据结构的构造或初始化都应指定大小避免数据结构无限增长吃光内存
3.	推荐及时清理不再使用的代码段或配置信息
说明对于垃圾代码或过时配置坚决清理干净避免程序过度臃肿代码冗余
正例对于暂时被注释掉后续可能恢复使用的代码片断在注释代码上方统一规定使用三个斜杠(///)来说明注释掉代码的理由。 


Then that’s it.

Thanks!

If you like my blog, please :

Please indicate the source of forwarding and be a follower of my Github.

By the way, if you have any questions or there is something wrong here, please contact me on Email:

haokinus@gmail.com