整理自知乎我的一次回答:http://www.zhihu.com/question/20594192
我的观点,只写说明性注释,不写功能性注释。也就是说,注释Why,而不是How和What。
类和函数多写文档注释,多少行无所谓,写在最前面,只要你是注释的Why。
函数内部,尽量少写注释。如果你的代码需要写注释来说明他的功能,那么这段代码就需要重构,最简单的方法,最简单的方法:提取函数。这样的好处是,函数名就是注释。一个错误的观点就是 注释是给人看的,程序是给电脑看的。其实,程序是给人的,凑巧的是,它居然可以在电脑里运行。
《重构》一书写道:
每当感觉需要以注释来说明点什么的时候,我们就把需要说明的东西写进一个独立函数中,并以其用途(而非实现手法)命名。
每次我给别人讲解「选择排序」、「插入排序时」,他们都觉得太难了,而且几乎每本数据结构教科书都是写了一堆代码和注释,这丝毫没有降低这个算法的难度。
如果不写注释,而写成函数呢?
伪代码:
array_ordered = [] loop_all_element(array, function(i){ el = select(array[i+1, array.length]) push(array_ordered, el) ...... })
- 构建一个有序数组,初始为空,(PS:空数组肯定是有序的)
- 循环整个数组,进行如下操作:
- 从数组剩下的元素里面选择最小的(或最大的)
- 将最小元素放在有序数组的最后面(或者最前面)
不用我多解释,你一眼就知道(看我加粗的字),这是选择排序。
插入排序呢?大同小异,我就不详细写了。
所以,文档注释,多少无所谓。函数内、类内注释,能不写,就不写。
相关阅读:千万要避免的五种程序注释方式
相关推荐
电脑卡是个老生常谈的问题,我们在日常使用电脑时,要注意对电脑系统的整理和维护。选择一款合适的清理工具,定期对电脑系统进行清理很重要,不妨试试加速人生,一键式操作,全面提速你的电脑,轻松还你洁净顺畅的...
1. 单行注释:单行注释以"//"开头,直到行尾的所有内容都被视为注释。例如,以下是一个单行注释的例子://这是单行注释。 2. 多行注释:多行注释以"/*"开头,以"*/"结束。在这两个符号之间的所有内容都被视为注释。...
我们都知道,在写SPA的时候,我们可以通过配置vue-router来实现路由的重定向。 官方文档(以及ts类型)的定义中给出了这一选项: interface RouteConfig = { path: string, redirect?: string | Location | ...
我们在 Eclipse 中编译运行 Java 文件,可能看到的结果是类似这样的乱码:????。那么,这是为什么呢?我们先来看看整个字符的转换过程。 1. 在 Eclipse 窗口中输入中文字符,并保存成 UTF-8 的 Java 文件。这里发生...
老生常谈外链 站长要做到对症下药.pps
正如标题所言,《电子技术的老生常谈——接地》一文中提到的那样,尽管接地的基本概念在每一次培训和交流中都会被提及,但往往缺乏一个通用而全面的方法论指导。本文旨在深入探讨接地的各种类型、目的以及具体的实施...
- `i`(ignore case):表示不区分大小写,在匹配时不考虑字符的大小写。 - `m`(multiple lines):表示多行模式,在使用`^`和`$`时,不是匹配整个字符串的开始和结束,而是匹配每一行的开始和结束。 正则表达式的...
ProgressBar和ProgressDialog是Android开发中常见的两种进度条控件,用于展示任务执行的进度或等待状态。下面我们将深入探讨这两种控件的用法。 首先,ProgressBar是一个可以显示具体进度的组件,它可以是圆形或...
Java设计模式是在特定环境下,为了解决某类重复出现的问题而总结出来的一套成功或有效的解决方案。这些设计模式旨在提高代码的可重用性、可维护性和可扩展性。 设计模式通常包含以下几个关键要素: ...
关于我 :waving_hand: 嗨,我是Gabriel R. dos Santos。 :revolving_hearts: 我正在PuzlPlace上合作 ...无法识别的天才实际上是老生常谈。教育没有超过。教育界充满了愚蠢的人。毅力和决心一个人是强大的。”
在进行JavaScript编程的过程中,面向对象思想一直是一个核心的概念。面向对象编程(OOP)是通过创建对象来模拟现实世界的一种编程范式。在JavaScript中,对象可以通过不同的方法创建和定义。面向对象有三大基本特性...
在Android开发中,事件传递和处理机制是相当关键的一个部分,尤其对于用户界面的交互有着决定性的影响。本文主要探讨了Android系统如何处理触摸事件,通过拟人化的比喻来解释事件传递的流程,并通过实际代码示例进行...
- 老生常谈:常说的老话题,缺乏新意。 - 无稽之谈:毫无根据的说法。 - 劈波斩浪:形容克服困难,勇往直前。 - 万象更新:一切事物都焕然一新。 4. 音节补充完整: - nà mìng 受骗 - zhù fú 祝福 - sh...
老生常谈 :换源 刚准备换源,系统提示我有软件更新,那就更新呗,果断点击确定,更新完还让我重启( 其四劳紫辽,不管! ) 国外源太慢了,我换国内阿里源 # 使用图形界面换源 软件和更新 >> 下载自 >> 其他站点 >> ...
1. 运行命令 pecl install ds ...Collection Interface:包含本库中所有数据结构通用功能的基本interface。 It guarantees that all structures are traversable, countable, and can be converted to json using json_...
关于命名,最老生常谈的就是命名一定要有意义!!别看谭浩强!别看谭浩强!别看谭浩强! 变量、函数、宏等等都需要命名,清晰的命名是优秀代码的特点之一。命名的要点之一是名称应能清晰的描述这个对象,以至于一个...
这个内容是老生常谈了,主要问题就是IE6不支持 position:fixed 引起的BUG.当我们去搜索解决这个bug的垮浏览器解决办法时,绝大多数结果都是说使用 position:absolute 来替代解决,可是我们真的解决了么?没有,因为当页面...
80. 老生常谈:老书生经常讲的话,比喻人们听惯了的没有新鲜意思的话。81. 力透纸背:形容书法笔力遒劲,也形容诗文立意深刻,词语精炼。82. 临渊羡鱼:站在深渊边上希望得到鱼。比喻只有愿望而没有实际行动是徒劳的...