开发经验漫谈-编码规范

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

什么是代码规范

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

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

为什么需要代码规范

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

这里先说明很重要的一点,那就是代码是写给人看的,并不是机器,所以说代码要让别人好理解。

我们多数情况下都是团队开发,所以大家都约定好一个标准,更加有利于团队代码的可维护性。

团队中有老人离职、有新人加入,从代码规范中是可以看到这个团队的文化的传承的。

对自己也是个约束,不要太随意了。

如何制定规范

制定步骤:

首先看是否有官方规范。一些较新的编程语言通常会有自己的一些规范,例如Golang,大家可以参考官方的Effective Go(https://golang.org/doc/effective_go.html),建议遵守。

其次看是否有权威的、认同度高的规范。通常使用较广泛的语言会这样做,如php的psr1、2,建议遵守。

之后,才是我们团队来制定自己的规范。

团队规范注意:

尽量避免一言堂。因为是团队规范,所以是需要得到大家的认同的。

要经常反思,不好的地方和团队成员讨论不断调整。其实这也是要求团队成员开发时不断反思的一个过程。

规范简单易懂。

参与过的规范实例

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

Golang项目

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

变量

多个词之间用”_”(下划线)连接,如:prj_home

可导出全局变量每个词的首字母均大写,如:Prj_Home

包内部全局变量用“_”(下划线)开头,单词小写,如:_prj_home

函数

函数名称驼峰式,如:listPrj

类型

类型名用“t”开头,如:t_prj_item

可导出名称用“T”,如:T_Prj_Item

接口类型用“i”开头,如:i_logger

可导出接口类型用“I”,如:I_Logger

多名词规则同“变量命名规则”

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

这套规范帮助我们这些初学者在当时统一了风格,避免了混淆。

后续的同学也能很快理解当时的项目,所以项目虽早,但现在也很好的运行着。

随着Go越用越多,我们不断更新我们的规范,从命名上,项目的组织上,都一直经历着变化,目前最新可参考gobox项目代码(https://github.com/orgs/goinbox/dashboard)

PHP项目

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

综述

对于psr标准中已规定的部分,请遵照执行,这里不再赘述。

这里主要定义现有psr标准中未规范的部分。

变量

统一使用驼峰式

数组key

使用下划线分隔多词

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

统一放在等号右边

函数中参数如果提供默认值,等号两端是否有空格

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

结束语

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

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

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20180624G1HIPC00?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券