编程代码规范

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

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

如果代码只是自己用,再“奔放”的风格都没有问题(只要你愿意折腾自己)。但是,如果你的代码要共享或者和他人协作一起写代码,那就必须要收敛自己放荡不羁的灵魂和天马行空的想象力,按照团队制定的协作规范来完成代码工作。

以下整理笔者接触过的高频使用的代码规范,供大家参考,意犹未尽者,可阅读文末资料。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个提示,https://coolshell.cn/articles/1038.html
  • 如何写出无法维护的代码,https://coolshell.cn/articles/4758.html
  • 编程中命名设计那些事,https://coolshell.cn/articles/990.html
  • 代码大全(第2版),Steve McConnell,电子工业出版社,第11、31章
  • 代码整洁之道(Clean Code),Robert C. Martin,人民邮电出版社

发表评论

登录后才能评论
服务中心
服务中心
联系客服
联系客服
返回顶部