【读书笔记】《代码整洁之道》第4-7章

第四章——注释

是啥啊？

注解的恰当用法释弥补我们在用代码表达意图时遭遇的失败

反思：就是这玩意不是好的。。你表意不清才会有的。写好注释，不如先写好代码。

如果你发现自己需要协助时，再想想看是否有办法翻盘，用代码来表达。

为啥不好啊？

因为注视会撒谎，也不是说总是如此或有意如此，但出现的实在太频繁。注释存在的时间越久，就离其所描述的代码越远。

不准确的注解要比没注释坏的多。他们满口胡言。他们预期的东西永不能实现。他们设定了无需也不应在遵循的旧规则。

好代码或是好注释？

• 烂代码+好注释=烂
• 好代码+好注释=好

啥玩意是好注释啊？

• 法律信息
• 提供基本信息的注释
  
  • 返回值
  • 特定的参数
• 对意图的解释
• 阐述
• 警示
• TODO注解
• 放大
• 公共API中的javadoc

啥玩意是坏注释啊？

• 瞎xx说
• 废话
• 误导性注释
• 循规式注释
• 日志式注释
  有了git，要这个破鸡毛干啥？对不对？

• 废话注释
  emmm 感觉作者有点废话了？
  不行，大神绝对不会有错！

• 能用函数或者变量时，就别用注解

• 位置标记

• 括号口面的注解
  如果你的函数太长了，就缩短函数，别老整这没用的

• 归属与署名

• 注释掉的代码
  玩这个干xx毛
• HTML 注解
• 非本地信息
• 信息过多。
• 不明显的联系：
  注释及其描述的代码之间的联系应该是显而易见的
• 函数头
• 非公共代码中的javadoc

第五章：格式

目的：

先明确一下，代码格式很重要。代码格式不可忽略，必须严肃对待。代码格式关乎沟通，而沟通时专业开发者的头等大事。

why？

你今天编写的功能，极有可能在下一个版本中被修改，但代码的可读性却会对以后可能发生的修改行为产生深远影响。

5.2 垂直格式垂直格式：

啥玩意啊？

尽可能用大多数为200行、最长500行的耽搁文件构造出色的系统。

咋回事啊？

向报纸学习

源文件也要像报纸文章那样。
名称应当简单且一目了然。名称本身应该足够告诉我们是否在正确的模块中
源文件最顶部应该给出高层次概念和算法。细节应该往下逐次展开，直至找到源文件中最底层的函数和细节。

概念间垂直方向上的区隔

几乎所有的代码都是从上往下读，从左往右读。每行展现一个表达式或一个字句，每组代码行展示一条完整的思路。

这些思路用空白行区隔开来！！！！！

垂直方向上的靠近：

如果说空白行隔开了概念，靠近的代码行则暗示了他们之间的紧密关系。
所以紧密关系的代码应该相互靠近

反思：啥玩意是紧密关系啊？

http://blog.csdn.net/ldb987/article/details/78195053 这个是类和类之间的紧密关系啊。
代码块和代码块之间的紧密关系是什么呢？

垂直距离

反面现象：

你想要理解系统做什么，但却花时间和精力再找到和记住那些代码碎片在哪里

咋放啊？

关系密切的概念应该互相靠近

变量声明：

变量声明应尽可能靠近其使用位置。

• 本地变量：因为函数很短，本地变量应该在函数的顶部出现。

  • 实体变量：
    实体变量应该在类的顶部声明

  • 循环中的控制变量应该总是在循环语句中声明

  • 相关函数：如果某个函数调用了另外一个，就应该把它们放到一起，而且调用者应该尽可能放在被调用这上面。这样，程序就有个自然的顺序。

  • 概念相关：概念相关的代码应该放到一起。相关性越强，彼此之间的距离就该越短。——相关性应该建立在直接以来的基础上，如函数间调用，或函数使用某个变量。

5.2.5 垂直顺序

我们想自上向下展示函数调用以来顺序。也就是说，被调用的函数应该放在执行调用的函数下面。这样就建立了一种自顶向下贯穿源代码模块的良好信息流。

想读报纸文章一般，我们指望最重要的概念先出来，指望以包括最少细节的方式表述它们。我们指望底层细节最后出来

e.g.：

public class WikiPageResponder implements SecureResponder{
    protected WikiPage page;
    protected PageData pageData;
    protected String pageTitle;
    protected Request request;
    protected PageCrawler crawler;

public Response makeResponse(FitNesseContext context 

5.3横向格式

应尽力保持代码行短小

5.3.1 水平方向上的区隔与靠近

如果有较长的列表需要做对齐处理，那问题就是在列表的长度上而不是对齐上。

缩进

源文件是一种继承结构，而不是一种大纲结构。其中的信息设计整个文件、文件中每个类、累中的方法、方法中的代码块，也涉及代码块中的代码块（emmmm）

类中的方法相对该类缩紧一个层级。方法的实现相对方法声明缩紧一个层级。代码块的实现相对于其容器代码块缩紧一个层级，以此类推。

5.3.4 空范围

别干这事。。。

5.4 团队规则

大家一个方法好吧，要不然就要炸了

第六章：对象和数据结构