怎么样写出更好、也更简短的源码分析书

在刚开始撰写《Redis 设计与实现》的时候, 我的其中一个目标就是希望这本书在足够有用的情况下, 也能保持短小的边幅。

为此, 我特意对自己的写作方式和方法进行了一些改进。

在书本发布之后, 我得到了不少的读者反馈, 其中的一些都向我表示书本写得非常清晰且易读, 我想这和我在写作时所使用一些技术不无关系。

这篇文章就记录了我在撰写《Redis 设计与实现》时所使用的写作方法, 希望这些方法能激发那些同样撰写书籍/文章的人, 并创作出更多“好看”的书。

关注程序本身的抽象和设计,而不是源码细节

关注抽象和设计的书籍会比密密麻麻满是代码的书籍要易读、易懂。

当你描述的是程序的运作机制、抽象和设计,而不是代码时,你会惊讶地发现自己能说的其实非常少。

另外,因为代码被改变的几率要比设计被改变的几率高得多,所以如果一本书关注的是设计而不是代码,那么这本书所包含的内容的保质期就会更长。

分离书本和源码,让它们各司其职

书本专门以简单的文字、图片、表格、流程图、简短的代码或伪代码来描述高层次抽象。

而源码则负责底层的编码细节。

这样书本和源码就不会相互冲突,也不会造成重复。

如果可能的话,提供一份带注释的源码,它可以给那些有兴趣研究源码的读者以帮助,也可以和书本配合使用,相得益彰。

文章中应该避免出现大量代码,更不要大量粘贴源码

除了程序的核心数据结构之外,不要在书本中轻易包含程序的源码,而是使用伪代码来描述程序的运作过程。

只有在源码和伪代码一样简单/简短的时候,才考虑直接贴源码。

当然了,使用伪代码也有它自己的缺点 —— 伪代码是无法验证是正确还是错误的,所以需要对伪代码多进行检查,确保:

  1. 伪代码正确地反映了源码的行为
  2. 伪代码在逻辑上是正确的
  3. 伪代码正确地关注了源码的高层次动作,而不是低层次细节。比如说,如果你在遍历一个列表时,使用了 while 而不是 map 或者 for ,那么你的伪代码所关注的层次就很可能不够高。

不要假设读者的水平

如果你在写一本关于数据库的书,那么你会在书中介绍数据结构吗?会介绍算法吗?会介绍设计模式吗?

实际上,数据结构、算法、设计模式这些知识,在我写《Redis 设计与实现》的时候都有碰到,但我没有自己去介绍这些知识,我也没有假设读者是否已经懂得这些知识,我所做的,就是将这些知识的关键词链接到一些资料上:

  • 如果读者需要这些知识,他们可以通过链接找到这些资料,这可以防止部分读者因为缺失前提知识,而没办法了解下文的情况出现。
  • 另一方面,如果读者不需要这些知识,他们也可以安全地忽略这些链接,而不会被不需要的内容影响自己的阅读体验。这也可以保证书本本身的主题不被其他主题所干扰。

如果需要在书中介绍一些主题以外的知识时,用一个链接,将读者带到更权威、也更详细地介绍这些知识的地方(比如维基百科),而不是自己写一些这些知识的简化、也可能出错的版本。

不要写(太多)文字

文字可能是传达信息最传统、也最低效的方式之一,多考虑使用图片、表格、列表、流程图等多样化的方式来表示信息,而不要单单依靠文字。

当你写上一段长长的文字时,考虑能否用

  1. xxx
  2. yyy
  3. zzz

这样的列表方式来表示它。

当你写了一大段文字来表示程序的执行动作,或者判断条件时,考虑能否用一个流程图或者伪代码来代替它。

当你为了在多个维度的对象进行对比,而写了一大段文字的时候,考虑能否用一个表格/或者柱形图来表示这些数据。

很难单纯地用文字去描述一个内涵丰富、动作多样的对象,请考虑使用图片或者动态图片,甚至是视频来表现它。

举例子

有时候对于一个复杂的功能, 单纯地描述它的作用所能展现的事情是非常有限的, 而且也不利于读者理解。

碰上这样的问题时, 一个非常有效的办法就是举一个实际的例子, 通过例子来阐述行为, 并配合正文来介绍一个功能, 可以达到事半功倍的效果。

仔细分割章节,减低读者的负担,帮助他们保持自己的注意力

当人们在阅读,特别是在网上读书的时候,他们的注意力非常容易被其东西所分散。

要保持读者的注意力,必须保证每一章和每一节的长度都在合理的范围之内:每个小节只传达一个小的主题,并给读者一个正向的反馈,这样读者会更容易读完,并且信心满满地进入下一小节。

另一方面,有了良好分割的内容之后,即使读者在阅读的过程中被其他东西打断了,他们要再回到书本上来的成本也会低很多。

如果文章的边幅太长,或者分段太少,请考虑将文章的内容分割至更细的粒度。

huangz
2013.3.17

留言

comments powered by Disqus