首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >你好我好大家好--吐露一点我在编程规范上的心得!

你好我好大家好--吐露一点我在编程规范上的心得!

作者头像
1480
发布2019-11-15 20:47:09
4820
发布2019-11-15 20:47:09
举报
文章被收录于专栏:数据分析1480数据分析1480

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

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

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

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

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

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,人民邮电出版社
本文参与 腾讯云自媒体分享计划,分享自微信公众号。
原始发表:2019-11-14,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 数据分析1480 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档