编程代码规范

如果你读过别人的代码(不管编程语言是用的啥)，是否会遇到下面这些坑：

• 不知道代码怎么用，没有解释输入和输出的内容，也没给到示例；
• 代码没对齐就算了，竟然没有一行注释；
• 变量命名过于随意或者抽象，完全不能“望文生义”；

 

如果代码只是自己用，再“奔放”的风格都没有问题(只要你愿意折腾自己)。

但是，如果你的代码要共享或者和他人协作一起写代码，那就必须要收敛自己放荡不羁的灵魂和天马行空的想象力，按照团队制定的协作规范来完成代码工作。

 

以下整理笔者接触过的高频使用的代码规范，供大家参考，意犹未尽者，可阅读文末资料。

 

1. 代码开头

1.1 功能说明

功能说明主要有3部分：

• 代码实现了什么功能；
• 输入(Input)什么(内容、格式等)？
• 输出(Output)是什么？

对于有输入输出的代码来说，通常都会给到测试示例。

e.g. 该函数用于计算两点之间的球形距离

输入：tuple格式的经纬度坐标(x1,y1),(x2,y2)

输出：float距离(km)

 

1.2 使用场景

代码通常在什么条件下使用，或者什么业务背景下使用。

e.g. 该口径为收银台支付成功率KPI口径

即 在线支付成功订单数/在线生成订单数，订单数按拆分前的母单进行统计

对于要求严格的场景，还要说明开发的语言及测试过可运行的环境。

如果到网上找到的代码运行出错，最常出现的问题：

• 系统不兼容，e.g.源程序只支持在linux上运行)；
• 版本不兼容，e.g.Python3的代码在Python2上跑容易报错，或者某个调用的包已经更新，函数语法已经改变了；
• 输入不规范，输入值不符合代码定义的内容或格式

1.3 版本信息

版本号，修改(创建)日期，作者，修改内容(原因)

e.g. 20180613 v2 Ahong 修改XX指标的计算逻辑，因为业务在20180612做了XX调整；

e.g. 20180718 created by Ahong，抓取XXX网站课程信息，包括如下字段；

 

2.命名规范

所有涉及到命名的地方都需要注意，包括数据表名、函数名、变量名、文件名等等。

命名规范主要有3点：

• 望文生义，也就是功能性命名，看名字就知道是什么意思；
  e.g. 好的命名 OrderCount，不好的命名 r
• 清晰简洁，即在保证表达清晰无歧义的前提下，名称不要太长，但也不要缩写得都不知道原来的单词是啥了；
  e.g.好的命名 LocMaxNum，不好的命名 getMaximumNumberPosizition
• 用词统一，要制定统一的名称规范，比如业务线的名称，常用计量指标的缩写等，这类内部规范要整理并公示出来让大家可以随时可查；
  e.g. 金额使用amt，取值为0或1的字段用is_开头，编号类字段以_id结尾等
• 专业用词，如果某个对象有行业通用名称或者专门的英文单词，那就尽量使用这种通用性更强的单词，而不是自己创造或者用拼音(甚至拼音缩写)；
  e.g. 支付宝，用alipay比zhifubao更好，用zfb的童鞋可以反思一下

注：更多可参考《代码大全》第11章，《代码整洁之道》第2章及文末参考资料1和3

 

3. 注释及提示

“不写注释的长代码都是耍流氓”。

注释的目的：

• 说明意图，即告诉阅读者是出于什么原因才用这种方式来实现的；
• 给予提示，用“人话”说明代码的含义；
• 改动警告，此处代码非常重要，改动不当会有严重后果，慎改！

通常需要加注释的地方：

• 功能说明，e.g.这个函数做啥的，这句代码的目的是啥；
• 修订说明，为什么要修改这里，是因为有bug或者效率问题？
• 重点、难点、易错点，引起阅读者的特别注意，不要掉坑里，同时要说明正确的思路，或者为什么不是“常规做法”等；

“注释”是不参与代码运行的，“提示”则是参与代码运行的，比如交互界面上提示输入信息、展示程序运行的进度、提示程序报错的原因等——“提示”更偏向于“可感知的用户体验”这个层面。

提示主要是3类：

• 输入提示，一般有GUI交互的时候才会提示输入值的内容、格式等；
• 运行提示，一般提示进度、剩余时长、处理到第几个任务等信息，如果遇到意外，则抛出可能是什么地方出了问题，方便代码的使用者知道要调整什么内容；
• 输出提示，通常是打印输出值，e.g.跑机器学习模型的时候，重要的指标会直接打印出来；

 

4.结构规范

结构规范，是指让代码整体的可读性高，内容简洁、层次分明。

 

4.1 简洁

在实现代码功能且运行效率不受负面影响的前提下，代码尽可能简短。

如果有代码块会重复用到，那就封装成“模块”(比如写成函数来调用)。

e.g. 写SQL时合理使用临时表，而不是让整个代码非常长；

e.g. 常用的功能写成函数，而不是在相同的代码在不同的位置出现

 

4.2 对齐

对齐除了美观之外，还能体现出代码的层级性，比如定义函数、循环、判断等操作的时候都会进行缩进，以表示，接下来的代码执行是归属于上面一行的。

代码对齐的时候尽量用Tab键操作，尽量不要用空格来进行缩进对齐，一个是效率低，二是可能会报错。

e.g. python代码中Tab和4个空格不能混用.

 

4.3 分行

一般情况下，应该保证不用向后滑动滚动条才能看到完整的一行代码。

如果代码太长，就要适当分行，一般分行后通过缩进对齐来表示下面的代码和上面是一伙的。

 

4.4 分块

分块就是进行模块化，比如会重复用到的计算部分可以打包写成函数，某种程度来说模块化的目的之一是尽可能减少重复。

分块可以使代码看起来逻辑结构更清晰，也便于调试(可以单个模块进行调试)和后续维护。

 

5.文档规范

 

5.1 定时备份

或者即时备份，硬盘损坏、电脑宕机、病毒感染等都可能导致文件出问题，一定要备份，小心“辛苦工作几十年，一夜回到解放前”。不过现在的代码工具通常都会进行自动缓存，即使突然关机，大多时候也能恢复文档。

 

5.2 版本管理

每个版本由谁做了什么操作要有记录。当然也可以借助Git之类的工具进行版本管理，方便代码回滚。

 

5.3 其他因素

安全性、便捷性等方面也要考虑，一般商业使用的代码要考虑保密性，比如企业内部代码不能直接托管到github等平台，甚至某些核心代码也不能跨部门分享。

 

参考资料：

• 编程命名中的7+1个提示
• 如何写出无法维护的代码
• 编程中命名设计那些事
• 代码大全(第2版)，Steve McConnell，电子工业出版社，第11、31章
• 代码整洁之道(Clean Code)，Robert C. Martin，人民邮电出版社