坚信科学,分享技术

>>>尝试更加利于阅读的2014版科学院,以后都在新版上写。

Tag Archives: 文档写法

如何写一手好文档(好代码)?

好久没见。 中秋去了一趟草原,放空了大脑,回来灵感突发,对文档、代码写法这方面的感悟多了些,特记录一下。 一、什么样的文档(代码)叫做“好”? 任何一篇文档,目标都是给别人看懂。 任何一段代码,首先也都是别人能看爽了才是目标。 以上述“世界观”为准,很容易得到文档(代码)好不好的结论。 以80后小时候读的连环画为例,它就是优秀文档的典范。 像连环画这样优秀的文档,主要具备以下几个特点: 1.长篇被分成小节。 2.小节中关键页有图。 3.描述言简意赅。 4.页数固定不多。 典型地,如果在写文档(代码)时,能够做到上述四点,都是优秀的。 比如: PHP文档造福了多少PHP程序员,让PHP这门语言流芳百世、追随者众多。在PHP文档中,每一小节都进行了特别归类; 在关键位置还有不少例子代码; 每个方法的作用也是言简意赅; 每一小节的数量都不是很多。 再来看nginx代码,完全是一个大型服务端软件构建的一个范例。只看src目录中的源码,从一开始就分成了core、event、http、mail、misc、os,这样相当清晰明了的层级结构和定义,让后续很多事情方便扩展; 每一部分的代码都能够让读者一眼看明白是做什么的; 每个细节的方法长度也不是特别长; 每个分类里的内容也相对是固定的,后续的改进都是在plugin上比较多。 二、几种实际的土办法提高文档(代码)能力 在上述建立好了对好文档(好代码)的世界观之后,下面再分享一些总结出来的套路,如果前面世界观没理解透,只把这里的土办法理解了,也能写出来容易读的文档(代码)。 办法一、写文档先写段落标题,写代码先建分类目录(java叫做pa

Continue reading

Posted in 架构研究 | Tagged | Leave a comment