代码才是最好的注释
2010-10-30 01:54
183 查看
一直以来都存在代码注释的作用的讨论。很多人认为注释是不必要的,写注释那是因为代码可读性太差了。我也同意这个原则。如果必须添加注释,我觉得可以添加一些解释代码为什么,而不是做什么的注释。下面我举个例子说明该如何除去代码中的注释。
我们直接看代码,下面的代码是我要对注释进行清除的例子。(这段代码只是作为一个例子,没有做过多的考虑。)
这段代码是相当简单的。从礼物清单中挑选出不在已赠送的礼物列表中的而且不超过预算的第一份礼物。这段代码有如下几个问题:
1、方法过长
2、这个方法做的事情太多
3、可读性差,即使加了注释
4、注释告诉我们代码是干什么的,这些应该是代码自己的事情才对。
让我们开始整理一下这段代码。
首先,看下面代码段,非常明显,这些代码注释是不必要的。这种代码注释我们应该避免。它并没有提高代码的可读性,事实上起到了相反的效果。
接着,我将下面带注释的代码移动到一个分离的方法中。方法的命名可以来自给出的注释。
修改后的代码:
然后按照相同的方式继续下去,最终的代码如下:
这里有几件需要注意的事情:
1、一个大方法按照它的功能被分割成几个小方法,这样代码就比较容易阅读了。
2、每个方法大概4到5行,非常理想!
3、注释去掉了,但是目的却达到了。用代码来代替了注释。
译自:Better way to comment.. code it.
译者说明:
1、文章的那段代码很有特色,正在恋爱的男程可以试一下代码里面的方法。
2、确实用代码来代替了注释。
3、从文章可以看到这段代码的演变主要是将注释变成了函数名和变量名。
4、对于老外来说,英文和代码类似,所以这样做就非常受用,通过看函数名,变量名就能明白函数的功能,Clean Code书中也是这样建议的。
5、对我们来说第一语言是中文的,英语不好情况就不一样了,这就是为什么国人的建议大多要求注释详尽,让代码更易读易懂;而老外的建议几乎是尽可能的少。
6、我建议符合我们的国情:尽可能多的注释。
我们直接看代码,下面的代码是我要对注释进行清除的例子。(这段代码只是作为一个例子,没有做过多的考虑。)
public String recommendGift(double budget){ // get gifts from helper String[] gifts = giftHelper.getGifts(); String gift = null; for (int i = 0; i < gifts.length; i++) { gift = gifts[i]; // find out if gift already given boolean isAlreadyGiven = false; for (String given : giftsGiven) { if(gift.equals(given)){ isAlreadyGiven = true; break; } } // calculate rating and budget int x = rating * 200; boolean ok = budget < x; // if both conditions satisfy, give it. if(!isAlreadyGiven && ok){ giftsGiven.add(gift); // increment maintenance cost of the girlfriend maintenanceCost += budget; return gift; } } return gift; }
这段代码是相当简单的。从礼物清单中挑选出不在已赠送的礼物列表中的而且不超过预算的第一份礼物。这段代码有如下几个问题:
1、方法过长
2、这个方法做的事情太多
3、可读性差,即使加了注释
4、注释告诉我们代码是干什么的,这些应该是代码自己的事情才对。
让我们开始整理一下这段代码。
首先,看下面代码段,非常明显,这些代码注释是不必要的。这种代码注释我们应该避免。它并没有提高代码的可读性,事实上起到了相反的效果。
// get gifts from helper String[] gifts = giftHelper.getGifts();
接着,我将下面带注释的代码移动到一个分离的方法中。方法的命名可以来自给出的注释。
// find out if gift already given boolean isAlreadyGiven = false; for (String given in giftsGiven) { if(gift.equals(given)){ isAlreadyGiven = true; break; } }
修改后的代码:
private boolean isGiftNotAlreadyGiven(String gift) { boolean isAlreadyGiven = true; for (String given in giftsGiven) { if(gift.equals(given)){ isAlreadyGiven = false; break; } } return isAlreadyGiven; }
然后按照相同的方式继续下去,最终的代码如下:
public String recommendGift(double budget) { String recommendedGift = null; for (String gift in giftHelper.getGifts()) { recommendedGift = gift; if(isGiftNotAlreadyGiven(recommendedGift)&&isUnderBudget(budget)) { updateMaintenanceCostAndGiftsGiven(budget, recommendedGift); return recommendedGift; } } return recommendedGift; } private void updateMaintenanceCostAndGiftsGiven(double budget, String gift) { giftsGiven.add(gift); maintenanceCost += budget; } private boolean isUnderBudget(double budget) { int x = rating * 200; boolean ok = budget < x; return ok; } private boolean isGiftNotAlreadyGiven(String gift) { boolean isAlreadyGiven = true; for (String given in giftsGiven) { if(gift.Equals(given)){ isAlreadyGiven = false; break; } } return isAlreadyGiven; }
这里有几件需要注意的事情:
1、一个大方法按照它的功能被分割成几个小方法,这样代码就比较容易阅读了。
2、每个方法大概4到5行,非常理想!
3、注释去掉了,但是目的却达到了。用代码来代替了注释。
译自:Better way to comment.. code it.
译者说明:
1、文章的那段代码很有特色,正在恋爱的男程可以试一下代码里面的方法。
2、确实用代码来代替了注释。
3、从文章可以看到这段代码的演变主要是将注释变成了函数名和变量名。
4、对于老外来说,英文和代码类似,所以这样做就非常受用,通过看函数名,变量名就能明白函数的功能,Clean Code书中也是这样建议的。
5、对我们来说第一语言是中文的,英语不好情况就不一样了,这就是为什么国人的建议大多要求注释详尽,让代码更易读易懂;而老外的建议几乎是尽可能的少。
6、我建议符合我们的国情:尽可能多的注释。
相关文章推荐
- 代码才是最好的注释
- 代码才是最好的注释
- 代码才是最好的注释
- 如何为javascript代码编写注释以支持智能感知
- Eclipse中Java代码注释XXX、TODO、FIXME的意义
- 基于注释处理生成代码的RxBus[Deprecated!]
- 机器学习实战代码 第三章3-1注释
- Objective-C 【电商APP应用代码-系统分析-详细注释-代码实现】
- python 脚本(获取指定文件夹、指定文件格式、的代码行数、注释行数)
- Python实现判断一行代码是否为注释
- IE的有条件注释详解(附实例代码)
- Java代码注释规范(动力节点整理)
- vim代码注释 NERDCommenter的安装及使用
- java中代码的注释和快捷键
- ASP.Net 2.0 窗体身份验证机制-转+自己代码注释示例与更详细的说明
- 使用SandCastle和HTML Help 2.0集成XML代码注释到VS2005和VS2008
- 量子编程详解之一: QP-nano代码大餐之状态机函数详细注释
- 对日软件开发——代码注释
- 10个最“优秀”的代码注释
- theano-xnor-net代码注释4 bnn_utils.py