代码才是最好的注释

简介:

 一直以来都存在代码注释的作用的讨论。很多人认为注释是不必要的,写注释那是因为代码可读性太差了。我也同意这个原则。如果必须添加注释,我觉得可以添加一些解释代码为什么,而不是做什么的注释。下面我举个例子说明该如何除去代码中的注释。

    我们直接看代码,下面的代码是我要对注释进行清除的例子。(这段代码只是作为一个例子,没有做过多的考虑。)

复制代码
1  public  String recommendGift( double  budget){ 
2  //  get gifts from helper 
3  String[] gifts  =  giftHelper.getGifts(); 
4  String gift  = null
5 
 6  for  ( int  i  = 0 ; i  & lt; gifts.length; i ++ ) { 
7 
 8  gift  =  gifts[i]; 
9 
10  //  find out if gift already given 
11  boolean isAlreadyGiven  = false
12  for  (String given : giftsGiven) { 
13  if (gift.equals(given)){ 
14  isAlreadyGiven  = true
15  break
16 
17 
18 
19  //  calculate rating and budget 
20  int  x  =  rating  * 200
21  boolean ok  =  budget  & lt; x; 
22 
23  //  if both conditions satisfy, give it. 
24  if ( ! isAlreadyGiven  & amp; & amp; ok){ 
25  giftsGiven.add(gift); 
26  //  increment maintenance cost of the girlfriend 
27  maintenanceCost  +=  budget; 
28  return  gift; 
29 
30 
31 
32  return  gift; 
33  }
复制代码

这段代码是相当简单的。从礼物清单中挑选出不在已赠送的礼物列表中的而且不超过预算的第一份礼物。这段代码有如下几个问题:

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、我建议符合我们的国情:尽可能多的注释。





本文转自麒麟博客园博客,原文链接:http://www.cnblogs.com/zhuqil/archive/2010/10/30/1864882.html,如需转载请自行联系原作者


相关文章
|
4天前
|
存储 关系型数据库 分布式数据库
PostgreSQL 18 发布,快来 PolarDB 尝鲜!
PostgreSQL 18 发布,PolarDB for PostgreSQL 全面兼容。新版本支持异步I/O、UUIDv7、虚拟生成列、逻辑复制增强及OAuth认证,显著提升性能与安全。PolarDB-PG 18 支持存算分离架构,融合海量弹性存储与极致计算性能,搭配丰富插件生态,为企业提供高效、稳定、灵活的云数据库解决方案,助力企业数字化转型如虎添翼!
|
15天前
|
弹性计算 关系型数据库 微服务
基于 Docker 与 Kubernetes(K3s)的微服务:阿里云生产环境扩容实践
在微服务架构中,如何实现“稳定扩容”与“成本可控”是企业面临的核心挑战。本文结合 Python FastAPI 微服务实战,详解如何基于阿里云基础设施,利用 Docker 封装服务、K3s 实现容器编排,构建生产级微服务架构。内容涵盖容器构建、集群部署、自动扩缩容、可观测性等关键环节,适配阿里云资源特性与服务生态,助力企业打造低成本、高可靠、易扩展的微服务解决方案。
1313 5
|
2天前
|
监控 JavaScript Java
基于大模型技术的反欺诈知识问答系统
随着互联网与金融科技发展,网络欺诈频发,构建高效反欺诈平台成为迫切需求。本文基于Java、Vue.js、Spring Boot与MySQL技术,设计实现集欺诈识别、宣传教育、用户互动于一体的反欺诈系统,提升公众防范意识,助力企业合规与用户权益保护。
|
14天前
|
机器学习/深度学习 人工智能 前端开发
通义DeepResearch全面开源!同步分享可落地的高阶Agent构建方法论
通义研究团队开源发布通义 DeepResearch —— 首个在性能上可与 OpenAI DeepResearch 相媲美、并在多项权威基准测试中取得领先表现的全开源 Web Agent。
1356 87
|
2天前
|
JavaScript Java 大数据
基于JavaWeb的销售管理系统设计系统
本系统基于Java、MySQL、Spring Boot与Vue.js技术,构建高效、可扩展的销售管理平台,实现客户、订单、数据可视化等全流程自动化管理,提升企业运营效率与决策能力。
|
4天前
|
弹性计算 安全 数据安全/隐私保护
2025年阿里云域名备案流程(新手图文详细流程)
本文图文详解阿里云账号注册、服务器租赁、域名购买及备案全流程,涵盖企业实名认证、信息模板创建、域名备案提交与管局审核等关键步骤,助您快速完成网站上线前的准备工作。
194 82
2025年阿里云域名备案流程(新手图文详细流程)