写出清晰的代码

图片来源:xkcd.com

写代码的首要任务是让代码读起来清晰并容易理解。刚入门的程序员容易忽略这点。好的代码更容易调试和维护,并且含有更少的错误。就像写文章一样,当你写的文章用了合适的语法和标点符号时,你表达的信息就更清晰。写代码也是同样一个道理,当你需要去阅读和维护别人的代码时,你就知道好的代码风格有多重要了!这里我们以Java语言为例介绍一下怎样写出清晰的代码。

编写代码

  • 使你的程序和函数(或方法)简短并易于管理。
  • 使用确切语言的典范代码风格。
  • 使用直截了当的逻辑和流程控制。
  • 避免直接使用数字(除了-1, 0, 1 和 2); 而是给那些数字取一些有意义的名称。

命名惯例

这里是一些命名变量,方法和类的总的原则。

    • 使用能表达变量作用的有意义的变量名,选择拼写简单的名字,避免使用难懂的缩写。比如使用 wagePerHourhourlyWage,而不是 wph。使用 polygon 而不是 ppolypgon
    • 保持一致性。
    • 命名 boolean 变量和方法时要使它们的意思没有歧义,例如 isPrime() 或 isEmpty()contains()
    • 对于生命期很短的变量和用作循环索引的变量使用短名字(例如i)。
      对于重要的变量使用描述性强的变量名。
    • 避免使用像 footmp 这样的常用名或像 fred 这样的无意义的名字。
      尽可能使用所应用领域的专业术语。
    • 通过常量的意义来为其命名,而不它的数值,比如把常量命名为 DAYS_PER_WEEK 而不是 SEVEN
标识符 命名规则 举例
变量 变量名简短但是有意义,一般人能看出这个变量代表什么(而不是该怎么用)。以小写字母开头,使用驼峰标识法(混合大小写,除第一个单词小写,后面单词首字母大写)。 mass
hourlyWage
isPrime
常量 全部大写,以下划线分隔每个单词。 N
BOLTZMANN
MAX_HEIGHT
能代表类意义的名词,以大写字母开头,使用驼峰标识法c class Complex
class Charge
class PhoneNumber
方法 能代表方法作用的动词,以小写字母开头,使用驼峰标识法。 move()
draw()
enqueue()

注释

程序员通过注释来让读者理解你的程序是如何工作的。总的来说,代码向计算机或程序员解释做什么;注释向程序员解释为什么这样做。

  • 行注释
    行注释以 // (两个斜杠)开始并在行尾结束
    // 开始到行尾都是注释部分,会被编译器忽略
  • 块注释
    块注释以 /* (一个斜杠和一个星号)开始并以 */ (一个星号和一个斜杠)结束。
    所有在这两个分隔符里的内容(即使有多行)都为注释并被编译器忽略。
  • 强调注释
    强调注释是块注释的一种形式,可以吸引注意。

    /*---------------------------------------------------------
     *  Here is a block comment that draws attention
     *  to itself.
     *---------------------------------------------------------*/
  • Javadoc 注释
    Javadoc 注释是块注释的一种形式,以 /** (一个斜杠和两个星号)开头。典型的使用方法是用来自动生成类的API。
    参考Oracle的 How to Write Doc Comments for the Javadoc Tool
  • 确保注释与代码保持一致,当你修改代码时注意是否应修改相应的注释。
  • 注释不要仅仅解释代码是怎样工作的,注释应该描述你要做什么或者为什么要这么做,而不是怎样做。
    
    
    i++;      //  increment i by one
    
  • 为那些可能难懂的代码提供注释,或者更好的是,重写这些代码,让它不难懂。
  • 在每个文件开头放一个强调注释,里面包括你的名字,日期,程序的作用和如何运行程序。
    /*----------------------------------------------------------------
     *  Author:        Kevin Wayne
     *  Written:       5/3/1997
     *  Last updated:  8/7/2006
     *
     *  Compilation:   javac HelloWorld.java
     *  Execution:     java HelloWorld
     *
     *  Prints "Hello, World". By tradition, this is everyone's
     *  first program.
     *
     *  % java HelloWorld
     *  Hello, World
     *
     *----------------------------------------------------------------*/
    
  • 为每个重要变量名(包括所有实例变量)提供行注释,并将这些注释对齐。
    private double rx, ry;    //  position
    private double q;         //  charge
    
  • 为每个方法提供注释,解释方法的作用,输入的参数,返回的输出,和副作用。在你的描述中使用参数名。
    /**
     *   Rearranges the elements in the array a[] in random order
     *   using Knuth's shuffling algorithm.
     *
     *   Throws a NullPointerException if a is null.
     */
    public static void shuffle(String[] a) {
        ...
    }
    

空白字符

程序员在他们的代码中使用空白字符来使代码更具有可读性。

  • 一行中的语句不要多于一条。
  • 使用空行来把你的代码分隔成多个逻辑区。
  • 在所有二元操作符(例如, <=, =, +)和操作数之间放一个空格。
    <!– . operator is a separator, not a binary operator –>
    一个可能的例外是当要强调优先权时。

    a*x + b
    
  • 在关键词(例如, while,for, if)和它的开括号之间加一个空格。
  • for 循环内的每个表达式之间加一个空格。
    for(int i=0;i&lt;N;i++)

    vs.

    for (int i = 0; i &lt; N; i++)
    
  • 在参数列表的每个逗号后加个空格。
  • 在每个评论分隔符后加个空格。
    
    
        //This comment has no space           //  This comment has two
        //after the delimiter and is          //  spaces after the delimiter
        //difficult to read.                  //  and is easier to read.
    
  • 不要在分号前面加空格。
  • 不要在方法名和它的开括号之间放空格。
  • 在一块相关的代码中用空行来给代码分组,以提高可读性。
  • 用空格将代码对齐来提高可读性。
    int N      = Integer.parseInt(args[0]);      //  size of population
    int trials = Integer.parseInt(args[1]);      //  number of trials
    

缩进

程序员用格式化并使用缩进来展示程序的结果,就像大纲一样。

  • 避免一行超过80个字符。
  • 每行只放一个语句。
  • 缩进固定的空格数,推荐用2~4个空格。(个人习惯使用4个空格,这也是很多IDE的默认值)
  • 总是使用空格而不是Tab。
    当你按Tab键时,多数现代IDE插入多个空格而不是Tab – 这被称为软Tab,硬Tab是过时的:在以前Tab被用作数据压缩。
  • 每层代码嵌套都用一个新的缩进。
  • 对于花括号使用 K&R 或 BSD/Allman
    缩进风格,并保持风格一致。

    //  K&amp;R style indenting
    public static void  main(String[] args) {
        System.out.println(&quot;Hello, World&quot;);
    }
    
    //  BSD-Allman style indenting
    public static void main(String[] args)
    {
        System.out.println(&quot;Hello, World&quot;);
    }
    

 

参考:Robert Sedgewick 和 Kevin Wayne 的 Writing Clear Code

Advertisements

《写出清晰的代码》有1个想法

发表评论

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / 更改 )

Twitter picture

You are commenting using your Twitter account. Log Out / 更改 )

Facebook photo

You are commenting using your Facebook account. Log Out / 更改 )

Google+ photo

You are commenting using your Google+ account. Log Out / 更改 )

Connecting to %s