编写可读代码的艺术

编写可读代码,是基础中的基础,但又非常的重要,所以我把它放在了总结具体重构手段的开头,这个是必须要掌握的

• 日常开发中,大多数情况下我们都是team开发,并且往往阅读>编码,所以你的一举一动和编码习惯都会影响到他人,作为团队,统一编码风格是基本要求,写出具有可读艺术,自解释的代码是团队友好,至关重要的.

以下分别从命名,注释,逻辑,结构四个方面阐述如何写出可读代码

命名

带上有效信息

• 避免”泛化”的词
  
  • 所有的数据都可以叫做Data,详细化一些是不是更好,PersonalInfo,ImageContent
• 增加信息量
  
  • 带上单位
    
    • delay -> delayMS
    • size -> sizeMB
• 包含必要的解释
  
  • days -> daysSinceLastUpdate

有效用词,避免歧义

• 多余的词
  
  • convertToString() -> toString()
• 有歧义的词
  
  • result = filter(objects,"year <= 2016")filter究竟是保留(select)还是排除(exclude)

约定俗成,符合惯例

• 约定俗成
  
  • 循环变量:i,j,k
  • 表示范围:[begin,end],[first,last]

• 符合语感

  • 类名,变量名(名词或者动词):MemoryCache,ShoppingCart
  • 函数方法名(动宾结构):fillCache(),removeItem()

  • 简单操作无需别致:getXXX(),setXXX()

    注意使用编译器自动生成时(根据已有相应的变量命名)会造成一些混乱的函数命名,比如getter和setter函数.

  • 成对API,参数含义一致:

    • insert(int[] grades, int position)
    • remove(int[] grades, int position)

注释

注释一般分为类注释,函数注释,字段注释,异常注释,需要注意的是虽然注释对于理解程序有巨大的帮助但也不要乱用注释,尽量写出自解释的程序.

类注释

/**
 * 一句话功能简述
 * 
 * 功能详细描述,使用时需要注意的事项
 * @author [作者](必须) 
 * @see [相关类/方法](可选)
 * @since [产品/模块版本](必须)
 * @deprecated(可选)
 */

• @deprecated表示不建议使用该类或者接口

字段注释

• 字段注释比较简单,就不举例了,但需要注意的是,一定不要写不必要的注释,要有良好的命名,使代码有自解释的功能
  
  • private boolean isShouldCache;good
  • private boolean mCache;//是否需要缓存bad
  • //文件处理系统在5MS内一次处理文件的最大数量
public static final String MAX_NUM_HANDLE_FILES = 5000;good

函数注释

• 公有方法和受保护的方法需要详细注释,注释格式如下:
  函数还是以自解释优先,不要滥用注释

    /**
     * 一句话功能简述
     * 
     * 功能详细描述,使用时需要注意的事项
     * @param 参数说明
     * @param 参数说明
     * @return 返回类型说明
     * @exception/throws 异常说明
     * @see 相关内容
     * @since 起始版本
     * @deprecated 
     */
    private byte[] encodeParameters(Map<String, String> params, String paramsEncoding) {
        StringBuilder sb = new StringBuilder();
        try {
            for (Map.Entry<String, String> entry : params.entrySet()) {
                sb.append(URLEncoder.encode(entry.getKey(), paramsEncoding));
                sb.append("=");
                sb.append(URLEncoder.encode(entry.getValue(), paramsEncoding));
                sb.append("&");
            }
            return sb.toString().getBytes(paramsEncoding);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }
        return null;
    }

异常注释

• 常常在函数注释中使用,说明主要异常的类型以及在何时抛出
  

  @exception标注Runtime异常,@throws标注非Runtime异常

    /**
     * @throws IOException 当关闭流失败时抛出的异常
     */
    public void close() throws IOException {
        //相关代码
    }

逻辑

表达式的书写习惯

• if(10 >= length)和if(length <= 10)哪一个更好?
• if(mathGrade>englishGrade)和if(englishGrade < mathGrade)哪个更好?
  书写原则

• 变量与常量:变量在左常量在右

  你超过20了吗?20岁比你大吗?

• 变量与变量:小于号原则

  和数轴方向一致

循环表达式

• for:清晰的迭代关系和结束条件
• do-while,while:易出错,需要小心检查边界条件
  

  推荐使用for循环

结构

• 这个需要讨论的很多,放在后面重构的手段中慢慢研究,具体大概有这几种:
  
  • 简化函数,抽离,避免一个函数做过多的事情
  • 简化类,优化继承体系,灵活上移下移字段和相应函数
  • 优化多层嵌套循环
  • 合并条件表达式等等

总结:

• 
  
• 易于阅读:
  
  • 命名:可维护代码的基础
  • 注释:注释的时机和内容
• 易于理解
  
  • 逻辑:符合人的思维习惯
  • 结构:清晰明了
    

文是死的但人是活的,以上的方案都是一种建议,每个团队都有自己的特点,可以根据自己的团队选择合适的方案进行统一开发,只要能提高开发效率,编写出具有艺术气息的代码,都是非常OK的