编写可读代码的艺术读书笔记--审美与注释

审美

        大家都愿意读有美感的代码,通过把代码用一致的、有意义的方式“格式化”,可以使代码变得更容易读,并且读的更快。

  • 如果多个代码块作相似的事情,尝试让他们有相同的剪影。
  •   把代码按“列”对齐可以让代码更容易浏览。
  • 如果在一段代码中提到A、B和C,那么不要在另一段中说B、C和A。
  • 用空行把大块的代码分成逻辑上的“段落”。

该写什么样的注释

 为代码中的瑕疵写注释,有几种标记在程序员中很流行:


标记

通常的意义

FIXME

已知的无法运行的代码

HACK

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

XXX

危险!这里有重要的问题


应该记录下来的想法包括:

  • 对于为什么代码写成这样而不是那样的内在理由“指导性批注”。
  • 代码中的缺陷。
  • 常量背后的故事,为什么是这个值,可能选值的范围及其他可选值。
  • 在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的。

注释应当精确地描述函数的行为


       假设你刚写了一个函数,它统计一个文件中的行数:

     

  //Returnthe number of lines in this file.

       IntCountLines(string filename){…}

上面的注释并不是很精确,因为有很多定义“行”的方式,下面的注释对于这种实现方法更好一些:

//Count how many newlines bytes(‘\n’)are in the file.

Int CountLines(String filename){…}

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


例如,下面是一个用来移除部分字符串的通用函数:

//Remove the suffix/prefix of ‘chars’from the input of ‘src’

String Strip (String src,String chars){…}

这条注释不是很精确,但是一个精心挑选的例子就可以回答这些问题

//Example:Strip(“abba/a/ba”,”ab”)return “/a/”

String Strip(String src, String chars){…}


“具名函数参数”的注释


void Connect(int timeout, booluse_encrption){…}

//Call the function with commentedparameters

Connect(/*timeout_ms= */ 10,/*use_encryption = */ false);




评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值