《整洁规约代码简单说》

   

  去年有幸参加了公司的一个代码质量活动，现将当时撰写的文档分享下。代码规范要求有很多，需要实际开发过程中逐步遵守或改进。
   本篇文章篇幅较小(当时实际规约写了较多，但限于公司期刊文字输出要求仅截取了部分)

 

 

  最近公司举办代码质量pk，有幸自己写的部分代码被选中，结合本次竞赛及自己的理解谈谈《整洁规约代码简单说》。

  一个良好的系统，不仅依赖架构及项目管理，更与代码质量紧密相关，好的代码，既会在整洁与规约度较为可靠，也为后期维护、升级奠定了良好的基础。

  那如何写出整洁规约的代码？有如下小技巧可遵循。

 

 一、有意义的明确命名

  定义看得清、读得出、可搜索的明确名称，避免思维映射，比如

  1) String n; //名称  (n的定义需要注释来补充，没有做到名副其实)

    String userName; (修改下名称就能轻易知本意，减少模糊度)

    int l,O; (l与O变量名常被认为是"壹"和"零"，实际是小写字母l或大写字母O，因此定义的名称要避免误导) 

  2) 将类名和对象名定义成名词或名词短语，比如Customer、Account； 将方法名定义成是动词或动词短语，比如update、save

  3) 名称使用标准命名法(驼峰形式)，比如outputUserName / localHost / getMemberMessage等

 

 二、简单短小的函数和类

  1) 函数规约

   a 函数要易于阅读与理解，推荐20-30行的短小函数，减少占全屏的函数。

   b 定义只做一件事的简单函数，判断一个函数是否只做了一件事，看是否能再拆出一个函数。

   c 推荐定义零参数函数，其次是一元函数，再次是二元函数，尽量避免三元函数，超过三个参数则考虑将其封装成类进行传递。

 

  2) 类规约

  a 与函数一样，也应短小，使用单一权责的原则来界定类的范围，不要试着去创建一个包含几十个方法的“神级类”。

  b 提高类的内聚性，使方法与和变量结合成一个逻辑整体。

 

 三、精简准确与表达到位的注释

  1) 好的注释有法律信息，有对复杂代码段的意图解释，有对可能发生意外的警示注释，有公共的API编写良好的Javadoc。

  2) 坏的注释有自言自语的描述，有多余的注释(没有人喜欢看小说一样的注释)，有详细的日志式注释。

  3) 能用函数或变量时就少用注释

  //会员集合包含某一会员号时说明是合法的会员

  if(memberModule.getMemberCodeItem().contains(memberBean.getMemberCode()))

 

  调整后的代码如下(无需注释知其意)

  ArrayList memberCodeItem = memberModule.getMemberCodeItem();

  String memberCode = memberBean.getMemberCode();

  if(memberCodeItem.contains(memberCode)) 

  充分使用git/svn等源代码控制系统，将注释掉的代码或冗余注释或不执行代码(死代码)及时清理，无需担心丢掉。

 

 四、垂直与横向的格式

  1) 垂直格式体现有短小精悍，推荐不超过500行，减少超过1000行的文件。超过2000行代码文件就如一篇长故事，故事中充斥着毫无组织的描述、日期、名字等，没人愿意去读它。

  2) 横向格式，建议无需拖动滚动条到右边的原则，比如单行字符数100个以内。

  良好的格式是我们与代码沟通最好的方式！

 

 五、日志使用

  1) 使用框架SLF4J中的API，比如门面模式，利于维护和各个类的日志处理方式统一，定义如下:

  private static final Logger logger = LoggerFactory.getLogger(MemberServiceImpl.class);

  2) 恰当使用error/warn/info级别的日志输出

  异常信息应该包括两类:现场信息和堆栈信息

  使用warn日志级别来记录输入参数错误的情况

 

  选择地输出info日志，避免把服务器磁盘撑爆

 

 六、错误处理

  1) 使用异常try-catch-finally而非返回码，不对大段代码进行try-catch。

  稳定代码指无论如何不会出错的代码(无需catch)，对于非稳定代码的catch尽可能进行区分异常类型，并做对应的异常处理。

  2) 防止NPE问题

  不使用null值做为返回值，减少调用者的非空判断，使用抛出异常或返回具体特例对象。

  不将null值传递给其它方法，减少报NullPointerException的异常。

 

我们都不想写出一个烂摊子代码，也想一直保持一切有序，进度可以重订，需求可以重新定义，团队动态可以修正，但糟糕的代码会一直腐败发酵，这无情地拖着团队的后腿(慢如蜗行)。而代码质量是程序员上百甚至上万次全心投入的结果，试着秉承《糟糕的代码可能毁了系统甚至毁了公司》这一警惕态度来不断的逐步改进写出更好的精练、简单、易于理解的代码。

如下为：公司技术期刊截图

转载于:https://my.oschina.net/devpmp/blog/3055235