关于代码规范的个人观点及伙伴个人项目的代码复审

一、代码规范

　　根据《代码风格不是代码规范》（http://www.vaikan.com/the-conventions-we-follow/）这篇文章的观点，代码风格与代码规范是不同的。我很认同这种观点。代码风格主要维护的是代码的可读性。而代码规范所涵盖的内容则要比代码规范广得多。

　　我个人的观点是，代码规范是十分有必要的。代码规范绝不是什么官僚主义的产物，也不是浪费大家时间的东西，而是一种能够有效地提高软件质量和开发效率的方法。为什么这样说呢？因为代码规范涵盖了两方面内容：一是代码本身的风格如何，二是代码的设计所应遵循的一些原则。在一个团队中，保持这二者的一致是十分有必要的。

　　一个团队共同开发软件和一个人独自开发软件有着一些明显的不同。我认为，团队项目的一些特点，使得我们在进行团队开发的时候，必须有代码规范进行约束。相较于个人开发，团队开发有着以下几个明显的特点：

• 团队项目中，不同模块由不同的人完成。而个人项目中，所有模块均由一人完成
• 团队项目的规模往往大于个人项目
• 团队中每个人的能力和水平不同，而个人项目则无需考虑这个问题
• 团队中，可能存在开发人员离开团队的情况

　　那么，如果我们不制定代码规范，那么由于上述这些特点的存在，会产生很多问题。首先，如果没有统一的接口风格以及错误处理方式，那么可能每个人返回错误信息的方式都不一样。比如有些人通过返回值返回，有些人抛出异常，又有些人会给传入的变量赋一些特殊的值以表明出现了错误。那么，我们在调用他人所写的模块的时候，就可能遇到种种问题。一会儿要检查返回值，一会儿又要注意异常的，一不小心可能就记错了。团队中每个人的水平都不一样，如果有人水平不高，总是不知不觉地使用一些很危险的用法或者可能隐含错误的方法，那么可能会给整个团队的开发都带来负面影响。例如下面这个例子:

1 // 某人的代码
2 #define FUNC(x) x+x
3 // 一般应该写作 FUNC(x) ((x)+(x)) 最为安全
4 
5 // 别人使用的时候
6 int k = FUNC(x)*2;
7 // 出错了，别人本意是计算(x+x)*2，但结果却算的是x+x*2

这样的错误有时候极难调试，如果我们在代码规范里提前写清宏定义的相关规范，那么我们就能够避免很多诸如此类的错误。同样，很多易错的、容易造成问题的写法，如果我们能够在代码规范里提前写清相关的用法，那么就能够在一定程度上避免不少问题的发生。

　　同时，统一的代码规范有利于团队的成员之间相互理解其他人的代码。由于代码风格的相对统一，每个人的代码从直观感觉上更为相近。这样有利于避免一些由于代码风格等引起的争端，也有利于大家去复查、审核其他成员的代码。否则，每个人的风格都不一样，对于代码复审等环节也会造成一些不必要的麻烦。

　　当然，代码规范的制定应当由整个团队共同完成。特别是代码风格，不应当强行去要求大家都不熟悉的一些风格，或者是只有极少数成员使用的风格。而应该将大家比较习惯的风格综合起来，形成代码规范里的代码风格。否则，代码规范就真成了官僚主义的产物了。另外，由于代码规范需要每个人都遵守，因此在规范制定时，需要大家共同参与，需要所有人都理解每一条规则是为了什么。否则，空有代码规范而无人遵守，那么要代码规范何用？

 

二、伙伴个人项目代码复审

Note: Y for positive or correct, N for negative or wrong

General

 

• ( Y ) Does the code work? Does it perform its intended function, the logic is correct etc.
• ( Y ) Is all the code easily understood?
• ( N ) Does it conform to your agreed coding conventions? These will usually cover location of braces, variable and function names, line length, indentations, formatting, and comments.
• ( Y ) Is there any redundant or duplicate code?
• ( Y ) Is the code as modular as possible?
• ( Y ) Is there any commented out code?
• ( Y ) Do loops have a set length and correct termination conditions?
• ( Y ) Can any of the code be replaced with library functions?
• ( Y ) Can any logging or debugging code be removed?

 

Security

• ( Y ) Are all data inputs checked (for the correct type, length, format, and range) and encoded?
• ( Y ) Where third-party utilities are used, are returning errors being caught?
• ( Y ) Are invalid parameter values handled?

 

Documentation

• ( Y ) Do comments exist and describe the intent of the code?
• ( N ) Are all functions commented?
• ( N ) Is any unusual behavior or edge-case handling described?
• ( Y ) Are data structures and units of measurement explained?
• ( Y ) Is there any incomplete code? If so, should it be removed or flagged with a suitable marker like ‘TODO’?

 

Testing

• ( Y ) Is the code testable? i.e. don’t add too many or hide dependencies, unable to initialize objects, test frameworks can use methods etc.
• ( N ) Do tests exist and are they comprehensive? i.e. has at least your agreed on code coverage.
• ( N ) Do unit tests actually test that the code is performing the intended functionality?
• ( Y ) Are arrays checked for ‘out-of-bound’ errors?