这几期想和大家分享下我自己在开发时的一些经验,这次来说说关于代码规范。

什么是代码规范

我理解的代码规范,是一个标准,让写代码的人按照这个标准来开发。

例如php的psr1(https://www.php-fig.org/psr/psr-1/)和psr2(https://www.php-fig.org/psr/psr-2/)

为什么需要代码规范

万事万物必然有其存在的意义,这里说下我的理解:

  1. 这里先说明很重要的一点,那就是代码是写给人看的,并不是机器,所以说代码要让别人好理解。
  2. 我们多数情况下都是团队开发,所以大家都约定好一个标准,更加有利于团队代码的可维护性。
  3. 团队中有老人离职、有新人加入,从代码规范中是可以看到这个团队的文化的传承的。
  4. 对自己也是个约束,不要太随意了。

如何制定规范

制定步骤:

  1. 首先看是否有官方规范。一些较新的编程语言通常会有自己的一些规范,例如Golang,大家可以参考官方的Effective Go(https://golang.org/doc/effective_go.html),建议遵守。
  2. 其次看是否有权威的、认同度高的规范。通常使用较广泛的语言会这样做,如php的psr1、2,建议遵守。
  3. 之后,才是我们团队来制定自己的规范。

团队规范注意:

  1. 尽量避免一言堂。因为是团队规范,所以是需要得到大家的认同的。
  2. 要经常反思,不好的地方和团队成员讨论不断调整。其实这也是要求团队成员开发时不断反思的一个过程。
  3. 规范简单易懂。

参与过的规范实例

这里举两个自己参与过的实例:

Golang项目

我们团队第一次使用Golang开发项目时,当时制定了这样的一套规范:

  • 变量
  1. 多个词之间用”_“(下划线)连接,如:prj_home
  2. 可导出全局变量每个词的首字母均大写,如:Prj_Home
  3. 包内部全局变量用“_”(下划线)开头,单词小写,如:_prj_home
  • 函数
  1. 函数名称驼峰式,如:listPrj
  • 类型
  1. 类型名用“t”开头,如:t_prj_item
  2. 可导出名称用“T”,如:T_Prj_Item
  3. 接口类型用“i”开头,如:i_logger
  4. 可导出接口类型用“I”,如:I_Logger
  5. 多名词规则同“变量命名规则”

当时制定这套规范时,我们对Golang的使用还是刚刚起步,很多不理解的地方,所以这套规范现在看来,很多地方都不合适,但在当时,还是起到了很大的作用。

  1. 这套规范帮助我们这些初学者在当时统一了风格,避免了混淆。
  2. 后续的同学也能很快理解当时的项目,所以项目虽早,但现在也很好的运行着。
  3. 随着Go越用越多,我们不断更新我们的规范,从命名上,项目的组织上,都一直经历着变化,目前最新可参考gobox项目代码(https://github.com/orgs/goinbox/dashboard)

PHP项目

这个项目也是我们团队的一个编码规范的典型运用,规范如下:

  • 综述

对于psr标准中已规定的部分,请遵照执行,这里不再赘述。 这里主要定义现有psr标准中未规范的部分。

  • 变量

统一使用驼峰式

  • 数组key

使用下划线分隔多词

  • 判断时常量在等号左边还是右边

统一放在等号右边

if ($a === 0){}
  • 函数中参数如果提供默认值,等号两端是否有空格

function foo($a = 0){}

这个项目的编码规范由当时我们团队的五个人共同制定,我们列出psr中未规定的部分,每个人陈述自己的观点,然后举手表决。

结束语

规范不是目的,只是一种手段,好的规范十分有助于编程人员培养良好的编程习惯。

最后,请记住一点:代码是写给人看的,机器只需要0和1。