xkcd.com

编写代码的首要任务是让代码读起来清晰并容易理解。好的代码更容易调试和维护,并且含有更少的错误。就像写文章,当你的文章用了恰当的语法和标点符号时,你表达的信息就更清晰。这里我们以Java语言为例,简单介绍一些基本的代码风格规则。

编写代码时

  • 使你的程序和方法简短并容易管理,一个类或者方法过长容易导致代码结构混乱
  • 使用特定语言的命名惯例(此文以Java的命名惯例作为例子)
  • 使用直截了当的逻辑和流程控制
  • 避免使用“魔法数字”(除了-1, 0, 和 1); 而是给那些数字取一些有意义的名称,例如 SUCCESS, FAILURE, DAYS_PER_WEEK

命名惯例

Java 命名通常采用驼峰命名法:单词之间不使用分隔符,除第一个单词小写,后面单词首字母大写,并将缩写视为单词。这里是一些命名变量,方法和类的总的原则。

  • 使用能表达变量作用的有意义的变量名,选择拼写简单的名字,避免使用难懂的缩写。比如使用 wagePerHour 或 hourlyWage, 而不是 wph。使用 polygon 而不是 p 或 poly 或 pgon
  • 保持风格一致。不要在一个地方使用 hourlyWage这样的风格,而在另一个地方却用 hourlywage 或 hourly_wage 这样的风格
  • 命名返回值为 boolean 类型的变量和方法时要确保它们的意思没有歧义,例如 isEmpty, hasNext, canWrite, shouldAbort, containsKey, exists, equals
  • 对于生命周期很短的变量和用作循环索引的变量可以使用短名字(例如i, j)。对于重要的变量要使用描述性较好的变量名
  • 尽可能使用所应用领域的专业术语。避免使用像 foo, bar 和 myFunction 这样无意义的名字(这些命名只是用于示例代码)
  • 对于常量,根据常量的意义来为其命名,而不它的数值。例如把常量命名为 DAYS_PER_WEEK 而不是 SEVEN
标识符 命名规则 例子
变量 简短但是有意义,一般人能看出这个变量代表什么。使用驼峰命名法,首字母小写 mass, hourlyWage, httpRequest
常量 全部大写,单词之间使用下划线分隔 TAG, MAX_SIZE
能代表类意义的名词,使用驼峰命名法,但是首字母需大写(又被称作帕斯卡命名法) Person, CoffeeMachine, UriMatcher
方法 能代表方法作用的动词,与变量命名规则一样,使用驼峰命名法,首字母小写 move, getValue, updateUi

注释

  • 除非代码意思非常明显,否则就要为代码编写注释
  • 给意思不是特别明显的变量编写注释,解释变量作用
  • 注释应该描述你要做什么或为什么要这么做,而不是仅仅解释代码是怎样工作的
  • 为每个方法都编写 Javadoc 注释,除非方法名本身就能完全清楚地解释其作用
  • 确保注释和代码保持一致,当你修改代码时注意是否也应该修改相应的注释

空白字符

在代码中适当的地方使用空白字符来使代码更具有可读性

  • 使用空行来把你的代码分隔成多个逻辑区
  • 在所有二元操作符(例如 +, *, =, >=,)和操作数之间放一个空格,例如:
y = a * x + b;
  • 在关键词(例如 while, for, if)和它的开括号之间放一个空格,例如:
while (condition) {
}

if (condition) {
}
  • 在 for 循环内的每个表达式之间加一个空格,例如:
for (int i = 0; i < N; i++) {
}
  • 在参数列表的每个逗号后加个空格,例如:
new Point(x, y, z);
  • 在每个评论分隔符(//)后加个空格,像这样:
// This is a good comment style

而不是这样:

//This is a not so good comment style
  • 不要在分号前面加空格
  • 不要在方法名和它的开括号之间放空格
  • 在一块相关的代码中用空行来给代码分组,以提高可读性

其他

  • 避免一行代码过长(通常一行代码在80,100或120个字符以内)
  • 每行只放一条语句
  • 每层代码嵌套都用一个新的缩进
  • 推荐使用 K&R 缩进风格。左花括号放在行尾而不是单独占用一行。例如:
class MyClass {
    int someMethod() {
        if (something) {
            doSomething();
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

总结

此文以Java为例简单地介绍了一些基本的代码风格,关于代码风格还有很多内容。专业的程序员或团队都会遵循一个优秀的代码风格规范。不同的代码风格规范内容会略有不同,但是最基本的代码风格几乎都是相同的,就像是有一个所有专业程序员都遵循的标准。

除了好的代码风格,要写出清晰的代码还需要好的架构,有效应用好的设计模式等多方面的考虑。这些需要长期的积累,正如 Peter Norvig 所说的:10年学会编程。但是从最基本的开始,养成良好的编程习惯是非常关键的一步。

关于更加全面的代码风格,可参考一些规范文档:

Google Java Style Guide

Twitter Java Style Guide