如果你读过别人的代码(不管编程语言是用的啥),是否会遇到下面这些坑:
如果代码只是自己用,再“奔放”的风格都没有问题(只要你愿意折腾自己)。
但是,如果你的代码要共享或者和他人协作一起写代码,那就必须要收敛自己放荡不羁的灵魂和天马行空的想象力,按照团队制定的协作规范来完成代码工作。
以下整理笔者接触过的高频使用的代码规范,供大家参考,意犹未尽者,可阅读文末资料。
1. 代码开头
1.1 功能说明
功能说明主要有3部分:
对于有输入输出的代码来说,通常都会给到测试示例。
e.g. 该函数用于计算两点之间的球形距离
输入:tuple格式的经纬度坐标(x1,y1),(x2,y2)
输出:float距离(km)
1.2 使用场景
代码通常在什么条件下使用,或者什么业务背景下使用。
e.g. 该口径为收银台支付成功率KPI口径
即 在线支付成功订单数/在线生成订单数,订单数按拆分前的母单进行统计
对于要求严格的场景,还要说明开发的语言及测试过可运行的环境。
如果到网上找到的代码运行出错,最常出现的问题:
1.3 版本信息
版本号,修改(创建)日期,作者,修改内容(原因)
e.g. 20180613 v2 Ahong 修改XX指标的计算逻辑,因为业务在20180612做了XX调整;
e.g. 20180718 created by Ahong,抓取XXX网站课程信息,包括如下字段;
2.命名规范
所有涉及到命名的地方都需要注意,包括数据表名、函数名、变量名、文件名等等。
命名规范主要有3点:
注:更多可参考《代码大全》第11章,《代码整洁之道》第2章及文末参考资料1和3
3 注释及提示
“不写注释的长代码都是耍流氓”。
注释的目的:
通常需要加注释的地方:
“注释”是不参与代码运行的,“提示”则是参与代码运行的,比如交互界面上提示输入信息、展示程序运行的进度、提示程序报错的原因等——“提示”更偏向于“可感知的用户体验”这个层面。
提示主要是3类:
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等平台,甚至某些核心代码也不能跨部门分享。
参考资料: