编写可阅读代码的艺术(4~6)

六 7th, 2013

4. 审美

核心思想: 如何使用好的留白,对齐和顺序来让你的代码变得更容易

4.1 重新安排换行保持一致和紧凑

 

4.2 用方法来整理不规则的东西

 

4.3 在需要时使用对其列

整齐的列可以很方便阅读

 

4.4 将声明用块组装起来

最好按逻辑分组,比如说功能块分组

 

4.5 把代码分成段落

 

4.6 个人风格与一致性

一致的风格比正确的风格更重要

5. 该写什么样的注释

核心思想: 不要为那些从代码本身就能推断的事实写注释

5.1 不要为了注释而注释

函数的声明与其注释时一致的,这类注释要删除或者改进它(增加更多的细节)

 

5.2 不要给不好的名字加注释---应该把名字改好

好代码 > 坏代码 + 注释

 

5.3 记录你的思想

1. 加入导演评论

//出乎意料的是,对于这些数据用二叉树比哈希表快40%

//哈希运算的代价比左/右比较大得多

2. 为代码的瑕疵写注释

当代码需要改进:

//todo:  采用更快算法

标记          通常的意义

todo          我还没处理完的事情

fix me        已知的无法运行的代码

hack          对一个问题不得不采用比较粗糙的解决方案

xxx           危险,这里有重要的问题

3. 给常量加注释

 

5.4 站在读者的角度

1. 意料之中的提问

2. 公布可能的陷进

3. 全局观注释

4. 总结性注释

 

5.5 克服”作者心里阻滞”

1. 不管想什么,先写下来

2. 读一下注释,看看有什么地方需要改进

3. 不断改进

 

6 写出言简意赅的注释

核心思想: 注释应该有更高的 信息/空间 率

6.1 让注释保持紧凑

 

6.2 避免使用不明确的代词

如  it,this 等到底指代什么需要从代码中去获取,最安全的办法就是将这些代词换成明确的词,如 data

 

6.3 润色注释

 

6.4 精确描述函数的功能

例子:如统计一个文件中的行数

//Return the number of lines in this file

上面没有明确行的定义,是\n,还是\n\r,或者是\r

修改为:

//Count how many newline byte(‘\n’) are in the file

 

6.5 用输入/输出的例子来说明特别的情况

 

6.6 声明代码的用途

 

6.7 “具名函数参数”的注释

 

6.8 采用信息含量高的词

当你发现注释非常长的时候,就得考虑是否可以用一个编程场景来描述它。

 





除非注明,本站文章均为原创。本文基于 BY-NC-SA 协议进行授权,欢迎转载,演绎或用于商业目的,但是必须保留本文的署名 metaboy(包含链接).

本文链接地址: http://blog.wangyuxiong.com/archives/51999

订阅本站:http://www.wangyuxiong.com/feed

分类: 读书笔记         标签:
目前还没有任何评论.

无觅相关文章插件,快速提升流量