读书笔记-编写可读代码的艺术[上]

观点：程序员之间的互相尊重体现在他所写的代码中。他们对工作的尊重也体现在那里。代码最重要的读者不是编译器，解释器或电脑，而是人。写出的代码能让人快速理解、轻松维护、容易扩展的程序员才是专业的程序员。

《编写可读代码的艺术》一书，专注于如何编写可读性更好的代码。

本文概要总结了这本书的第1部分内容。

1.代码应当易于理解

1.1是什么让代码变得“更好”

示例1

for(Node* node = list->head;node != NULL;node = node->next){
   print(node->data);
}

Node* node = list->head;
if(node == null){
  return;
}
while(node->next != NULL){
 print(node->data);
 node=node->next;
}

if(node != null){
   print(node->data);
｝

示例2

return flag >0 ? "Fans":"fans";

if(flag >0){
  return "Fans";
}else{
  return "fans;
}

第1个版本更紧凑，第2个版本更直白。哪个标准更重要呢？

1.2可读性基本定理

代码的写法应当使别人理解它所需要的时间最小化。

"别人"应当指所有阅读你的代码的人，包括同事，也包括6个月后的你自己！

1.3总是越小越好吗

一般来讲，解决问题的代码越少就越好。很可能理解100行代码写成的类所需要的时间比1000行要短。
但少的代码并不总是最好。

return flag >0 ? "Fans":"fans";

if(flag >0){
  return "Fans";
}else{
  return "fans;
}

比下面的代码花更多时间：

value = findValue(key);
if( value != null && !value.isOccupied()){
 //do sth
}

1.4理解代码所需的时间是否与其它目标有冲突
其它目标：更有效率，好的架构，容易测试？

1.5最难的部分
经常思考是否容易理解，需要额外的时间。（短期）
写出更少缺陷，更容易改进的代码。（长期）

第一部分 表面层次的改进

2.把信息装到名字里

2.1选择专业的词
getPage(url);
是从缓存获取页面，还是实时从互联网上获取呢？

更专业的词：fetchPage,downloadPage。

2.2避免象tmp这样泛泛的名字

String tmp =user.name();
tmp += " "+user.email();

用userInfo这样的名字更具有描述性。

建议：tmp这个名字只应用于短期存在且临时性为其主要存在因素的变量。

2.3用具体的名字代替抽象的名字
serverCanStart：检测服务是否可以监听某个给定的TCP/IP端口。
更好的名字：canLinstenOnPort。这个名字直接地描述了这个方法要做什么事情。

2.4为名字附带更多信息

var start  = new Date().getTime();
//do sth
var end = new Date().getTime();

var costTime = (start-end)/1000;

(时间的单位是秒s，还是毫秒ms？)
costTimeMs?

2.5名字应该有多长
d,days,daysSinceLastUpdate
在小的作用域可以使用短的名字，大的作用域使用长的名字。
看看当前上下文是否有足够的信息。

2.6利用名字的格式来传递含义

//常量名和类名的取名方式不一样
public static final int MAX_NUMBER= 100;

public class Number{

}

3.不会误解的名字

3.1容易产生误解的例子
 

allPersons.filter(“age>100”);
 

//挑出？减掉？

3.2推荐用first和last来表示包含的范围
   推荐用begin和end来表示包含/排除范围

 

  String str ="abcd";
   str.substring1(int first,int last);
   str.substring2(int bigin,int end);

   
3.4给布尔值命名
  

boolean addUser(){

     boolean flag= true;
     return flag;
   ｝
     

把flag换成addSucceed
   

3.5与使用者的期望相匹配
 

String name;
  //很多程序都习惯了把以get开始的方法当作“轻量级访问器”这样的用法，它只是简单地返回一个内部成员变量。
  private String getName(){
    return name;
  }
 
  //bad
  private String getName(){
    return "My name is:"+Name+" !";
  }

4.审美

4.1把声明按块组织起来

//get/query/find/select 查询类方法

//add  增加类方法

//update 修改类方法

//delete 删除类方法

4.2把代码分成“段落”

String name;
uddateName="";

String email;
sendEmail();

String address;
saveAddress();

4.3个人风格与一致性

class Name{

}

class Name
{

}

一致的风格比“正确”的风格更重要。

5.该写什么样的注释
5.1什么不需要注释

//The class definition for Name.
class Name{

}

建议：不要为那些能从代码本身快速推断的事实写注释。

5.2记录你的思想
加入“导演评论”

//准确率可以达到99%，没有必要达到100%
getValue();

为代码中的瑕疵写注意
//冒泡排序不够快
bubbleSort();

给常量加注释
//人的最大年龄
public static final int MAX_AGE=150;

5.3站在读者的角度

公布可能的陷阱
//调用外部服务来发送邮件。（1分钟之后超时）
sendEmail();

“全局观”注释
//这个类包含一些辅助函数，为我们的文件系统提供了更便利的接口

总结性注释
//求和
int[] array = {1,2,3};
for(int index=0;index<array.length;index++){
  sum += array[index];
}

5.4最后的思考-克服“作者心理阻滞”
很多程序员不喜欢写注释，因为要写出好的注释感觉好像要花很多功夫。
当作者有了这种“作者心理阻滞”，最好的办法就是现在就开始写。
先写，再优化。

6.写出言简意赅的注释
建议：注释应该有很好的信息/空间率
6.1让注释保持紧凑

//求和（计算第1个到最后1个元素的和）
int[] array = {1,2,3};
for(int index=0;index<array.length;index++){
  sum += array[index];
}

6.2精确地描述函数的行为

//返回文件的行数
//计算换行符（
）的个数
int countLines(String fileName);

6.3采用信息含量高的词
//这个类包含很多成员用来存储和数据库中相同的一些信息，为了提高速度。
//当这个类被读取的时候，检查这些成员是否存在，如果存在直接返回，不存在就存储。

简单地说：
//这个类作为数据库的“缓存层”(Caching Layer)。

原文链接：http://FansUnion.cn/articles/1892