编写可读代码的艺术-从命名和注释开始

什么样的代码才是真正好的、整洁的代码？iteye.com上的文章很多：
Grady Booch，《面向对象分析与设计》作者：
引用
    • 整洁的代码是简单、直接的；
    • 整洁的代码，读起来像是一篇写得很好的散文；
    • 整洁的代码永远不会掩盖设计者的意图，而是具有少量的抽象和清晰的控制行。
Dave Thomas，OTI公司创始人，Eclipse战略教父：
引用
    • 整洁的代码可以被除了原作者之外的其他开发者阅读和改善；
    • 具备单元测试和验收测试；
    • 有一个有意义的名字；
    • 使用一种方式来做一件事情；
    • 最少的依赖，并明确定义；
    • 提供了一个清晰的、最小的API；
    • 应该根据语言特性，在代码中单独显示必要的信息，而不是所有的信息。
     
从他们的归纳中，可以看出真正好的代码都有一个共性，可读性。在《编写可读代码的艺术》这本书中，作者是这样定义可读性的：“代码的写法应当使用别人理解所需的时间最小化”。在这本书的指导下，从命名和注释开始在自己这几年写的代码中找出一些例子。希望自己以后在这些细节上引以为戒。
一.把信息封装到名字中，无论是类，方法或变量的命名

    1.选择专业的词,尽量避免模糊或意义太广 。

 public List<UserIp> select(String userId){
 }

      如果改成这样是不是更明确：

 public List<UserIp> queryUserIps(String userId){
  }

 

    2.避免泛泛的名字
        避免像tmp,i,j ,k这样泛泛的名字，比较常见循环中的 i,j,k.

        for (int j = 0; j < actionLogs.size(); j++) {
           ActionLog actionLog = actionLogs.get(j);
         }

 
    如果改成这样：

        for (int index = 0; index < actionLogs.size(); j++) {
           ActionLog actionLog = actionLogs.get(index);
         }

 

    3.用具体的名字代替抽象的名字
    在给变量，函数或者其它元素命名时，要把它描述的更具体而不是更抽象。

        /**
         * 刷新IP库
         */
        public void refreshData() ;

    如果改成这样：

      /**
         * 刷新IP库
         */
        public void refreshIpData() ;

 

   4.使用前缀或后缀来给名字附带更多信息
        对于像带单位的值均可以用后缀来附加更多信息
        常见的打印日志的代码：

         long startTime = System.currentTimeMillis();  
         if (logger.isInfoEnabled()) {
                        logger.info(（System.currentTimeMillis() - startTime) + "ms,success!");
         }

 

     如果改成这样：

 long startMs = System.currentTimeMillis();  
         if (logger.isInfoEnabled()) {
                        logger.info(（System.currentTimeMillis() -  startMs ) + "ms,success!");
         }
    

 

    5.决定名字的长度
    （1）在小的作用域里可以使用短的名字，丢掉没用的词。

   public static StrategyType convertToStrategyType(StrategyTypeDO strategyTypeDO) {
         }

 

       如果改成这样：

      public static StrategyType toStrategyType(StrategyTypeDO strategyTypeDO) {
         }

 
    6.给boolean命名
        通常来讲，加上is,has,can 或should这样的词，可以把布尔值变得更明确。
        如代码：

        boolean first = true;
                if(subConditions!=null&&subConditions.size()>0){
                    for (FactorCondition condition : subConditions) {
                        String template = generateCode(condition);
                        sbf.append((first ? "" : " || ") + "( " + template + " )");
       
                        if (first) {
                            first = false;
                        }
                    }
                }

 

    若改为：

           boolean isFirst = true;
            if(subConditions!=null&&subConditions.size()>0){
                for (FactorCondition condition : subConditions) {
                    String template = generateCode(condition);
                    sbf.append((isFirst ? "" : " || ") + "( " + template + " )");
   
                    if (isFirst) {
                        isFirst = false;
                    }
                }
            }

 

    7.与使用者的期望相匹配
        方法的名称要符合用户的期望，我们通常期望get()方法是轻量的方法。

public double getFPSecurityModelScore(Event event) {
            //这里省略
           }

 

        若改为：

 public double computeFPSecurityModelScore(Event event) {
            //这里省略
           }

 

二.代码风格与注释

      一致的风格要比“正确”的风格更重要，对于一个团队乃至一个公司，要采用一致的格式化模板。对于注释，一定不要为注释而注释，许多时候好代码>坏代码+注释，当你觉得要写很多注释时，也从侧面反映出你的代码或设计不太美妙。注释的目的就是尽量帮助读者了解和作者一样多。
   
       1.不要为了注释而注释

  /**
         * Getter method for property <tt>groupName</tt>.
         *
         * @return property value of groupName
         */
        public String getGroupName() {
            return groupName;
        }
   
        /**
         * Setter method for property <tt>groupName</tt>.
         *
         * @param groupName value to be assigned to property groupName
         */
        public void setGroupName(String groupName) {
            this.groupName = groupName;
        }

 

    当然，上面的的注释是由模板生成的，确有为了注释而注释之嫌。
   
    2.注释要记录你的思想.

      包括为什么代码写成这样而不哪样的内在理由。对于代码的缺陷或需要优化的地方可给予注释，对于常量，可记录常量背后的故事，为什么是这个值，如：

        /**
         * The load factor used when none specified in constructor.
         */
        static final float DEFAULT_LOAD_FACTOR = 0.75f;

 

   
    3.站在读者的立场上思考。

     为普通读者意料之外的行为加上注释，用注释来总结代码块或精确地描述函数的行为，使读者不致迷失在细节中。

三.细节决定成败，表面并非肤浅
    对于上面的每一个细节如果都能做的很好，这就为写好代码，写好可读代码，写好整洁代码迈出了第一步。

参考资料：《编写可读代码的艺术》