【代码注释】浅谈对于代码注释的理解
楔子:“这里的山路十八弯,这里的水路九连环”;智慧的古人就懂得,通过把山路修成九曲十八弯来战胜陡峭的高坡。看则舍近求远绕圈而行,实为拿路程换高度,为完成登顶而蓄势待发。这种螺旋上升亦进亦退的智举,在生活中也不胜枚举。
代码,源自一门门计算机程序设计语言,就是人类与计算机之间交流的桥梁。代码注释,顾名思义,就是对这些特别的语言更加符合人类自然常识的解释,换句话说就是用更加通俗的方式让别人甚至自己理解代码的含义。
Level 1:犹记当年初窥编程世界之时,一些基础入门级别的书籍在介绍到代码注释这一部分的时候,都会不约而同的强调“大家一定要学会写好注释”,大体上给人的初步印象就是,代码注释多多益善。
Level 2:有了一定编程基础之后呢,一般大家都会兴致勃勃的写上一两个练手级的小项目,在不断应用上新技术的同时,“多写注释”的四字箴言早已经被抛在脑后。而且呢,一般一个逻辑不太复杂的小项目经过自己耐心的调试之后,也能够最终华丽丽的问世。沉浸在小小的成就感的同时,不禁在脑中可能就形成了“注释这个东西有点鸡肋呀,你看我也没怎么用到注释,不也把这么nice的项目给整出来了嘛(傲娇脸)”。
Level 3:画风一变,开始接触一些企业级的大项目了。不管是从需求分析开始接手也好,还是半途拿到别人的项目也罢,惊人的代码量,复杂的系统逻辑,整个人都蒙了!!!此时可能无需旁人多言,自己也会想把大腿拍青,”代码注释真是太重要了!别说接手别人的项目时需要通过注释才能快速理解整个项目,就连自己亲手写的代码,一旦庞大起来,时间已久,不看注释也完全不知道从何下手了,详细的注释真是能做到事半功倍!“
Level 4:阅历越来越丰富的我们,开始不断听到这样的声音”代码注释产生的原因,究其根本是代码本身的可读性太差!“,先抛开不管这样的观点是出自业内泰斗还是初生牛犊之口,仔细琢磨一下这句话,确实有一定的道理。如果代码可读性很强,使人一目了然,那干嘛还要另外添加注释呢?这样一解读,其逆反命题也很有道理呢。(哈哈哈,这里就不卖关子了,其实很多编程大作之中,也都有提到这样的观点)
Level 5:深得注释要领的我们,开始把更多的精力投入到代码自身的可读性上面去,写出了漂亮的代码的同时,开始减少注释的量。然后出任CEO,迎娶白富美,走上人生巅峰。。。然后梦就醒了2333;两眼一睁,发现自己在项目经理的办公室里,他老人家也在同时发现了醒来的你,开始破口大骂:”你是第一天做项目吗?你这光秃秃的代码是在逗我吗?注释都没时间添?“当你据理力争,解释一通之后,经理可能长叹一口气,然后语重心长的对你说:”孩子,咱们是在中国呀!“众所周知,中国特色码农主义世界里,跳槽是一件多么频繁的事情(这里就不做深入讨论了)。你的项目不写上详实的注释,再加几个说明文档,负责人甚至会以为你想撂挑子不干了!
Level max:从“需要写注释”到“不需要写注释”,又从“注释多多益善”再到“代码越好注释越少”,最后还要考虑下本国国情(捂脸)Orz,就在这一进一退之中,我们对于注释的认识也在螺旋上升中。可能这个问题本身就不存在一个标准的答案(那我们还一直纠结这个问题干嘛!有病?),但是这样的矛盾,可能就是我们提高的桎梏,一个体现水准体现内力的地方。一般情况下,我们可以官方性的把“要不要写注释”这样的问题归结为:根据情况结合自己的经验而定~((╯‵□′)╯︵┻━┻这种情况还是上点干货好了,比如这样一段代码:
1 public void fun() { 2 ToolOne t1 = Tool.getInstance(); 3 t1.setAttr("xxx","yyy"); 4 t1.setUrl("zzz"); 5 t1.execute(Tool.DEFAULT); 6 7 ToolTwo t2 = Tool.getInstance(); 8 t2.setAttr("xxx","yyy"); 9 t2.setUrl("zzz"); 10 t2.execute(Tool.DEFAULT); 11 12 ToolThree t3 = Tool.getInstance(); 13 t3.setAttr("xxx","yyy"); 14 t3.setUrl("zzz"); 15 t3.execute(Tool.DEFAULT); 16 }
这样一段代码,不管是方法名还是内容,谁能知道这是在干嘛!那么我们是要加注释喽?比如这样:
/**把大象装进冰箱里*/ public void fun() {//第一步:把冰箱门打开ToolOne t1 = Tool.getInstance();t1.setAttr("xxx","yyy");t1.setUrl("zzz");t1.execute(Tool.DEFAULT);//第二步:把大象塞进去ToolTwo t2 = Tool.getInstance();t2.setAttr("xxx","yyy");t2.setUrl("zzz");t2.execute(Tool.DEFAULT);//第三步:把冰箱门关上ToolThree t3 = Tool.getInstance();t3.setAttr("xxx","yyy");t3.setUrl("zzz");t3.execute(Tool.DEFAULT); }
这样是不是一目了然了呢~哈哈哈,那么我们来看一看高级点的办法,就是以代码来充当注释,看招:
public void take_elephant_into_icebox() {openIcebox();setElephantIn();closeIcebox(); }public void openIcebox(){ToolOne t1 = Tool.getInstance();t1.setAttr("xxx","yyy");t1.setUrl("zzz");t1.execute(Tool.DEFAULT); }public void setElephantIn(){ToolTwo t2 = Tool.getInstance();t2.setAttr("xxx","yyy");t2.setUrl("zzz");t2.execute(Tool.DEFAULT); }public void closeIcebox(){ToolThree t3 = Tool.getInstance();t3.setAttr("xxx","yyy");t3.setUrl("zzz");t3.execute(Tool.DEFAULT); }
如何,现在不管是从方法名take_elephant_into_icebox到方法体的三句代码,整个代码做到了不写一行代码也一目了然的效果,对于一般的阅读者来说,也能很清晰准确的理解这块代码的含义、运行逻辑和最后实现的功能。
所以嘛,身为一个并不资深的猿类,也已经意识到这个螺旋上升理解注释的模式,当然上面所分等级也仅限个人的一面浅见,level max并非绝对,仅为大家日后学习不断改进自己的认知水平而提供一个参考,总之也希望我们都能在这条遥不见终点的路上越走越远吧2333~To be continue......
转载于:https://www.cnblogs.com/YukiKun/p/5077396.html
【代码注释】浅谈对于代码注释的理解相关推荐
- 【Java】浅谈关于代码的耦合性
[Java]浅谈关于代码的耦合性 前言 一.需求 二.简单的实现 1.资源代码(项目提供) 2.对需求的普通实现 三.利用业务与逻辑分离的方式实现 改进 四.对需求改进后的同步项目改进(优点) 总结 ...
- 浅谈 我对 技术 的理解
文章目录 1.浅谈 我对 技术 的理解 1.1 技术 是 什么? 1.2 技术的 两个 核心 构成 要素 1.2.1 知识 层面 1.2.2 智慧 层面(思考 层面) 1.3 技术 很难?学不明白? ...
- html代码id,浅谈html中id和name的区别实例代码
浅谈html中id和name的区别实例代码 更新时间:2008年07月28日 23:00:55 作者: 这个是form里面的name与id的区别 我们可以通过一段代码来分析一下其中的微妙差别: 在 ...
- Linux位置无关代码实现,浅谈位置无关代码
原标题:浅谈位置无关代码 引言 最近参与的一个项目涉及到了二进制重写相关的问题,也因此看了几篇相关工具的论文.与之前曾经一直想做的动态装载有不少重合,因此在此做一个整理. 本文主要整理了动态库装载地址 ...
- python之代码可读性浅谈
python基础回顾--代码可读性解析篇 前言 在学习了一门编程语言之后,往往大部分人会急于使用代码实现自己的一些功能进行测试自己的学习情况,这是好的,但是在实际使用中代码却往往不是只给自己看的,或者 ...
- 浅谈Python代码风格规范 PEP8
浅谈Python PEP8 本文只简要谈及一下,python的编码风格指南-PEP8. PEP8 全称<Python Enhancement Proposal #8>译作:8号Python ...
- html中加一个空行,浅谈HTML代码中的空格和空行
HTML 代码中的所有连续的空格或空行(换行)都会被显示为一个空格. 例子1:(文本内容中的连续空格) 代码 XML/HTML Code复制内容到剪贴板 这段文本中,输入连续的空格 ...
- 浅谈对seo概念的理解
个人认为与微信一样,搜索引擎有固定的用户群体,有人有流量的地方,就存在商机或者利益,seo的概念就是搜索引擎优化,其目的是在搜索引擎中获得精准用户,获得流量.从更深层次方面看,利用seo做自然排名获得 ...
- linux代码签名,浅谈Linux容器和镜像签名(示例代码)
导读 从根本上说,几乎所有的主要软件,即使是开源软件,都是在基于镜像的容器技术出现之前设计的.这意味着把软件放到容器中相当于是一次平台移植.这也意味着一些程序可以很容易就迁移,而另一些就更困难. 我大 ...
最新文章
- 南通市公积金信息系统goldengate复制软件采购
- 《数学之美》第3章 统计语言模型
- mysql+8.0+新特性_MySQL 8.0的一些新特性汇总大全
- mysql windows软件_windows版MySQL软件的安装
- GDKOI2021总结
- WSUS离线导入更新包
- 蓝桥杯 ALGO-67 算法训练 最大值与最小值的计算
- php 数组 判断可以吗,php判断一个数组是否为有序
- 对网上盛传的两千万泄漏数据的简单分析
- 易语言大漠插件模块制作窗口获取窗口句柄类
- 火山PC大漠插件源码开源学习--木塔老师
- Opencontrail 流的处理
- c语言程序设计第五版第四章例题
- onenote同步速度慢
- 面试时如何更好的介绍自己的项目
- 【计算机网络】第九章:无线网络
- 【ROS小车课设】虚拟机端编译riki工作空间问题解决
- zynq 7000 的HDMI 显示实验
- 网易视频云CEO余利华:云服务的核心仍是用户体验
- python3 生成器的send_Python3基础 yield send 获得生成器后,需要先启动一次
热门文章
- C++编译动态库第三方库及使用
- protect 继承_c++三种继承方式public,protect,private
- 剑三游戏总是显示服务器繁忙,剑网三缘起:终究低估了老玩家的热情,服务器被挤爆...
- 详细解析电源滤波电容的选取与计算
- 【cookbook pandas】学习笔记 chapter9 grouping,aggregation,filtration,and transformation
- 常用前端JS代码与JS方法
- Windows CMD 常用命令指示符
- CGB2106-Day01
- git 入门教程之回到过去
- [Android ] seekbar ,去除自定义thumb滑块不透明背景