基础编码规范

关于专业

程序如同一本小说，写出来是给人阅读的，包括作者自己。一本结构清晰、逻辑严密、富含人生哲理的小说阅读起来让人折服。相反，一本头重脚轻、错漏百出、只为赚钱而胡乱拼凑起来的小说阅读起来味如嚼蜡。同样的，对于程序员来说，排版整洁、注释清晰、算法合理的代码阅读起来让人舒畅，而缩进不一、命名拙劣、只有编译器才能读懂的代码阅读起来让人痛苦。和作家写小说、音乐家作曲、建筑师画设计图、导演拍电影一样，程序员编写代码应该具备专业精神，把程序当成是自己的艺术作品来看待。

 

入乡随俗

每一种编程语言都有她自身语法规则，程序员在使用该语言的过程中，会慢慢形成一些约定俗成的习惯。这些习惯包括变量的命名和函数方式、缩进的风格等。但往往这些习惯是只适合于该语言，如果一个新手在学习 B 语言的时候，把他原来熟悉的 A 语言的习惯直接套上去，那么大部分使用 B 语言的程序员看上去会觉得非常别扭，有些时候甚至会造成沟通障碍。所以当我们学习一种新的编程语言的时候，在学习其语法的同时，也建议多阅读这门语言的经典代码，慢慢了解这些习俗，不要把其他语言的习惯照搬进来。

 

排版

排版的要求主要分成宏观排版和微观排版两种。

 

宏观排版

所谓宏观感觉就是读者第一眼看到代码时候的感受。如果代码的缩进统一，相同逻辑快的代码比较紧密，不同逻辑块的代码有所分隔，那么读者单凭这个宏观的排版就基本上可以判断出程序的逻辑结构。另一方面，如果宏观排版整洁，读者会先入为主地认为你的代码写得不错。

 

缩进

统一使用 4 个空格来缩进。不要使用 tab 来缩进。用 tab 来缩进有一个很不好的地方，当相同的代码放到不同的编辑器里面显示，差别可能会很大。因为不同的编辑器可能对 tab 的长度做了不同的定义，有些编辑器设置了用空格来替换 tab，当多个人编辑过同一份代码后，缩进就会变得不统一，整份代码的可读性就会变差。不要使用两个空格来缩进。两个空格很难直观地看出作用域，特别是代码量大了以后。

 

断行

当一个表达式太长的时候就要考虑断行，因为看一行很长的代码很吃力，甚至还要左右滚屏。断行有讲究，如在不恰当的地方断行，会打断读者的思路，更会埋下错误的陷阱。关于在哪里断行合适，有以下几个原则：

• 在逗号后面断行
• 在运算符前面断行
• 尽量不要打断语句

断行后的开始位置要增加一层缩进。如：（Python 语法）

# 好的断行
loooooooooong_method(expr1, expr2,
        expr3, expr4, expr5);
 
# 好的断行
good = a * b / (c - g + f) \ # 注意：保留断行前的空格
        + 4 * z;
 
# 不好的断行
bad = a * b / (c - g \ # 注意：(c - g + f) 这个语句被打断了
       + f) + 4 * z;

 

疏与密

关系紧密的代码行紧靠在一起，关系疏的代码行之间留空行。如：（Python 语法）

def foo():
    # say hello
    print 'Hello World'
 
    # print 1 - 10
    for i in range(10):
        print i + 1
 
    # print 11 - 20
    for i in range(10, 20):
        print i + 1

 

微观排版

这个是指在一行代码里面，变量、括号、运算符等元素的连接方式。

 

一空格原则

当在一行内需要对各个元素进行分隔时，只能用一个空格。举个反例：（Python语法）

def foo():
    print a +  b # 注意：加号后面用了两个空格

 

括号

括号内侧不留空格，举例：（Java 语法）

// 不好的风格
if ( ( a-b ) > 0 ) {
    // ...
}
 
// 好的风格
if ((a-b) > 0) {
    // ...
}

 

流程控制语句

流程控制语句与左括号中间要有一个空格。如：（Java 语法）

import java.util.Stack;
 
public class Test {
    public static void main(String args[]) {
        Stack<Integer> items = new Stack<Integer>();
 
        // 压10个元素进盏
        for (int i = 0; i < 10; i++) { // 注意：for 和左括号之间留一空格
            items.push(i);
        }
 
        // 弹出盏中的各个元素，分单双数打印
        while (!items.empty()) { // 注意：while 和左括号之间留一空格
            int i = items.pop();
            if ((i % 2) == 0) {
                System.out.println("even: " + i);
            } else {
                System.out.println("odd: " + i);
            }
        }
    }
}

 

运算符

二元运算符两端要有一个空格。如：（Python 语法）

def foo():
    print (1 + 2) * 3

 

注释

注释是用来帮助读者了解代码逻辑的，起到提示的作用。注释的使用要合理，过多过少都是不好的。如果注释太少，读者碰到较复杂的算法，或者特殊的业务规则，就会很难理解，读不下去；如果注释太多，把逻辑都用注释写一遍，就会很啰嗦，后面更改逻辑后还要修改注视，维护成本高。 所以注释不要喧宾夺主，大部分时候读者还是阅读代码为主，只在关键的地方其提示作用。下面针对注释提出四点要求：

• 文件注释：每个文件的头部必须包含对该文件代码的简要说明，必要的情况下要加详细说明。
• 函数注释：10 行以上的函数前面必须包含对该函数的简要说明，必要的情况下要加参数和返回值的说明。
• 流程注释：不要把代码片段翻译成注释。如果加了这类注释，每次修改代码的后，要更新对应的注释。
• 废弃代码：废弃的代码不要用注释的方法保留在文件中。如果保留了，那必须是日后可能会启用的。

 

命名

要考察一个程序员的编码能力，首先要看他的命名水平，因为好的命名是程序可读性的基础。不好的命名有很多种，但好的命名总能让读者顾名思义。下面针对命名提出两点基本要求：

• 符合英语命名习惯：大部分编程语言都是基于英语的大环境的发展起来的，不论程序员的母语是什么，命名的时候都要尽量使用英语，这样有助于你和世界上大部分程序员交流。要写出符合英语习惯的命名，平时就要多读英语文档，多读优秀程序的源代码，慢慢提高自己的英语基础。
• 符合该语言命名习惯：每一门主要的编程语言都会有很多程序员使用，这些程序员在平常的交流中会慢慢形成一套符合该语言特性的命名习惯。学习这些命名习惯就是我们学习一门新语言的时候首先要做的事情，而不是将我们之前学过的其他编程语言的名习惯照搬过来。

 

小结

上面列出来的都是最基础的编码习惯，但也是很多程序员在编程多年后都没有形成的习惯。没人能够一步登天，万丈高楼从地起，贝多芬也不是天生就会作曲的，任何一门技术都会有一个苦练基本功的过程。如果我们想我们的编程能力上一个台阶，想在编程领域有所作为，必须扎扎实实地把编码的基本功练好。