不知道代码怎么用,没有解释输入和输出的内容,也没给到示例;
代码没对齐就算了,竟然没有一行注释;
变量命名过于随意或者抽象,完全不能“望文生义”;
以下整理笔者接触过的高频使用的代码规范,供大家参考,意犹未尽者,可阅读文末资料。
代码实现了什么功能;
输入(Input)什么(内容、格式等)?
输出(Output)是什么?
e.g. 该函数用于计算两点之间的球形距离
输入:tuple格式的经纬度坐标(x1,y1),(x2,y2)
输出:float距离(km)
e.g. 该口径为收银台支付成功率KPI口径
即 在线支付成功订单数/在线生成订单数,订单数按拆分前的母单进行统计
系统不兼容,e.g.源程序只支持在linux上运行);
版本不兼容,e.g.Python3的代码在Python2上跑容易报错,或者某个调用的包已经更新,函数语法已经改变了;
输入不规范,输入值不符合代码定义的内容或格式
e.g. 20180613 v2 Ahong 修改XX指标的计算逻辑,因为业务在20180612做了XX调整;
e.g. 20180718 created by Ahong,抓取XXX网站课程信息,包括如下字段;
望文生义,也就是功能性命名,看名字就知道是什么意思;
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或者效率问题?
重点、难点、易错点,引起阅读者的特别注意,不要掉坑里,同时要说明正确的思路,或者为什么不是“常规做法”等;
输入提示,一般有GUI交互的时候才会提示输入值的内容、格式等;
运行提示,一般提示进度、剩余时长、处理到第几个任务等信息,如果遇到意外,则抛出可能是什么地方出了问题,方便代码的使用者知道要调整什么内容;
输出提示,通常是打印输出值,e.g.跑机器学习模型的时候,重要的指标会直接打印出来;
编程命名中的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,人民邮电出版社