[学习笔记]《代码整洁之道》（四）

[学习笔记] 《代码整洁之道》—第5章 格式

• 代码的格式很重要！代码的格式不可忽视，必须严肃对待！

垂直格式

• 垂直尺寸：源代码文件该有多大？

  • 有可能用大多数为200行，最长500行的单个文件构造出色的系统。
  • 这并非不可违背的原则，但短文件通常比长文件易于理解。

• 源文件要想报纸文章那样。名称简单且一目了然，

  • 源文件最顶部应该给出高层次概念和算法。
  • 细节应该往下逐次展开，直到找到源文件中最底层的函数和细节。

• 几乎所有的代码都是从上往下读，从左往右读。

  • 每行展现一个表达式或一个子句，每组代码行展示一条完整的思路；
  • 这些思路用空白行区隔开。
    • 没一个空白行都是一条线索，标识出新的独立概念。

• 如果空白行隔开了概念，靠近的代码行则暗示了它们之间的紧密关系。

  • 紧密相关的代码应该互相靠近。

    public class ReporterConfig{
        /**
         * The class name of the reporter listener
         */
        private String m_className;
        
        /**
         * The properties of the reporter listener
         */
        private List<Property> m_properties = new ArrayList<Porperty>();
        
        public void addProperty(Porperty porperty){
            m_porperties.add(porperty);
        }
    }
    
    //修改后
    public class ReporterConfig{
        private String m_className;
        private List<Property> m_properties = new ArrayList<Porperty>();
        
        public void addProperty(Porperty porperty){
            m_porperties.add(porperty);
        }
    }
    

• 关系密切的概念应该互相靠近。

  • 除非有很好的理由。否则就不要把关系密切的概念放到不同的文件中。
  • 对于那些关系紧密、放置在同一文件中的概念，它们之间的区隔应该成为相互的移动度有多重要的衡量标准。应该避免迫使读者在源文件和类中跳来跳去。

    • 变量声明应尽可能靠近使用位置。

    • 实体变量应该在类的顶部声明。1

    • 相关函数，若某个函数调用了另外一个，就应该把它们放到一起，而且调用者应该尽可能放在被调用者上面。

    • 概念相关的代码应该放到一起。

      • 相关性越强，彼此之间的距离就该越短。

        public class Assert{
            static public void assertTure(String message, boolean condition){
                if(!condition)
                    fail(message);
            }
            
            static public void assertTure(boolean condition){
                assertTure(null, condition);
            }
            
            static public void assertFalse(String message, boolean condition){
                assertTure(message, !condition);
            }
            
            static public void assertTure(boolean condition){
                assertFalse(null, condition);
            }
            ...
        }
        

• 被调用函数应该放在执行调用的函数下面。

横向格式

• 一行代码应该有多宽？

  • 应该尽力保持代码行短小;
  • 死守80个字符的上限有点僵化，100~120个字符可以接受。

• 用空个字符将彼此紧密相关的事物连接在一起，也用空格字符把相关行较弱的事物分离开。

  private void measureLine(String line){
      lineCount++;
      int lineSize = line.length();
      totalChars += lineSize;
      lineWidthHistogram.addLine(lineSize, lineCount);
      recordWidestLine(lineSize);
  }
  

  • 在赋值操作符周围加上空格字符，以此达到强调目的；

  • 不在函数名合作园括号之间加空格，因为函数和其参数密切相关；

  • 把函数调用括号中的参数一一隔开，强调逗号，标识参数是互相分离的。

  • 空格字符的另一种用法是强调其前面的运算符。

    public static double root1(double a, double b,double c){
        dpuble deteminant = determinant(a, b, c);
        return (-b + Math.sqrt(determinant)) /(2*a);
    }
    

    • 乘法因子之间没有加空格，因为它们具有较高优先级。
    • 加减法运算项之间用空格隔开，因为加法和减法优先级较低。

• 声明和赋值对齐是没有必要的。

• 源文件是一种继承结构，要让这种范围式继承结构可见 ------ 缩进。

  • 大多数类的声明，根本不缩进；
  • 类中的方法相对类缩进一个层级；
  • 方法的实现对方法声明缩进一个层级；
  • 代码块的实现相对于其容器代码块缩进一个层级；
  • 以此类推…
  • 别因为短小的if函数、while循环或小函数违反缩进规则。

• 如无法避免while或for语句的语句为空，确保空范围体的缩进，用括号围起来。

团队规则

• 如果你在团队中工作，则团队应该一致同意采用一套简单的格式规则，所有成员都要遵从！

参考文献

[1] Robert C. Martin 著，韩磊 译，《代码整洁之道》，北京：人民邮电出版社，2010.1（2018.9 重印), ISBN 978-7-115-21687-8。

---