数据库编程之注释规范
1.6 注释规范
注释规范是判断一个开发人员优劣和成熟度的重要指标。一个优秀的研发人员必然是经过深思熟虑然后才洋洋洒洒妙笔生花的,注释的书写体现了一个人思考问题的全过程和步骤;话又说回来,就算代码写的烂,只要注释写的好,至少也会给人以良好的感觉;同时也能造福后人,不是么?呵呵。
规则1.6. 1
一般情况下,源程序有效注释量必须在30% 左右。
说明:注释的原则是有助于对程序阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言须准确、易懂、简洁、精炼。
规则1.6. 2
统一文件头的注释.
主要是对相关过程、函数进行功能性描述、修订记录、以及入参出参说明
对存储过程、函数的任何修改,都需要在注释后添加修改人、修改日期及修改原因等修订说明。
/***********************************************************
名称: sp_xxx
功能描述:
修订记录:
版本号 编辑时间 编辑人 修改描述
1.0.0 2010-01-01 John 1 、创建此存储过程
1.0.1 2010-02-01 Sandy 2 、增加传入参数
入参出参描述:
iparameter1 IN VARCHAR2(20) 传入参数1
iparameter2 IN VARCHAR2(20) 传入参数2
iparameter1 OUT VARCHAR2(20) 传入参数1
iparameter2 OUT VARCHAR2(20) 传入参数2
返回值描述:( 主要针对函数)
0 - Success
1 - normal fail
***********************************************************/
规则1.6. 3
所有变量定义需要加注释,说明该变量的用途和含义。
规则1.6. 4
注释内容要清晰、明了、含义准确,防止注释二义性
在代码的功能、意图层次上进行注释,提供有用、额外的信息。
避免在一行代码或表达式的中间插入注释。
尽量使用”-- ”进行注释;行尾注释须使用”-- ”。
规则1.6. 5
对程序分支必须书写注释。
说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。
在程序块的结束行右方加注释,以表明程序块结束。
规则1.6. 6
注释应与其描述的代码相似,对代码注释应放在其上方或右方( 对单条语句的注释) 相近位置,不可放在下面。
注释与所描述的内容进行同样的缩排。
注释上面的代码应空行隔开。
建议1.6. 7
注释用中文书写
有一次,同事写了一个900 行的存储过程,里面定义了十几个游标以进行遍历,这个存储过程缺乏注释,执行一次居然要一天一夜,已经达到了无法容忍的地步。
因为缺乏注释,我花了整整一天的时间来对该存储过程进行分析,然后用了半天时间来进行改写和调试。
其实很简单定义,我定义了一些对应的临时表,把游标遍历替换成SQL 的集合操作,把整个的一个大事务分割成若干小事务,只是修改了部分代码,结果执行时间就变成了短短的3 分钟。
当然游标也并非不可触及的,既然存在就有他存在的理由。
【编辑推荐】
相关文章
- 从本体论开始说起——运营商关系图谱的构建及应用
- 如何成为一名数据科学家?
- 从未见过的堂兄杀了人,你的DNA是关键证据
- 20个安全可靠的免费数据源,各领域数据任你挑
- 20个安全可靠的免费数据源,各领域数据任你挑
- 阿里云李飞飞:All in Cloud时代,云原生数据库优势明显
- 基于Hadoop生态系统的一高性能数据存储格式CarbonData(性能篇)
- 大数据告诉你:10年漫威,到底有多少角色
- TigerGraph:实时图数据库助力金融风控升级
- Splunk利用Splunk Connected Experiences和Splunk Business Flow 扩大数据访问
- 大数据开发常见的9种数据分析手段
- 以免在景区看人,我爬了5W条全国景点门票数据...
- 【实战解析】基于HBase的大数据存储在京东的应用场景
- 数据科学家告诉你哪些计算机科学书籍是你应该看的
- Kafka作为大数据的核心技术,你了解多少?
- Spring Boot 整合 Redis 实现缓存操作
- 大数据学习必须掌握的五大核心技术有哪些?
- 基于Antlr在Apache Flink中实现监控规则DSL化的探索实践
- 甲骨文再次被Gartner评为分析型数据管理解决方案魔力象限领导者
- 爬取吴亦凡微博102118条转发数据,扒一扒流量的真假