坚信科学,分享技术

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

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

document

久没见。

中秋去了一趟草原,放空了大脑,回来灵感突发,对文档、代码写法这方面的感悟多了些,特记录一下。
54chen

一、什么样的文档(代码)叫做“好”?
任何一篇文档,目标都是给别人看懂。
任何一段代码,首先也都是别人能看爽了才是目标。

以上述“世界观”为准,很容易得到文档(代码)好不好的结论。

以80后小时候读的连环画为例,它就是优秀文档的典范。
连环画

连环画这样优秀的文档,主要具备以下几个特点:
1.长篇被分成小节。
2.小节中关键页有图。
3.描述言简意赅。
4.页数固定不多。

典型地,如果在写文档(代码)时,能够做到上述四点,都是优秀的。
比如:
PHP文档造福了多少PHP程序员,让PHP这门语言流芳百世、追随者众多。在PHP文档中,每一小节都进行了特别归类; 在关键位置还有不少例子代码; 每个方法的作用也是言简意赅; 每一小节的数量都不是很多。

再来看nginx代码,完全是一个大型服务端软件构建的一个范例。只看src目录中的源码,从一开始就分成了core、event、http、mail、misc、os,这样相当清晰明了的层级结构和定义,让后续很多事情方便扩展; 每一部分的代码都能够让读者一眼看明白是做什么的; 每个细节的方法长度也不是特别长; 每个分类里的内容也相对是固定的,后续的改进都是在plugin上比较多。

二、几种实际的土办法提高文档(代码)能力
在上述建立好了对好文档(好代码)的世界观之后,下面再分享一些总结出来的套路,如果前面世界观没理解透,只把这里的土办法理解了,也能写出来容易读的文档(代码)。

办法一、写文档先写段落标题,写代码先建分类目录(java叫做package)。
在一切开始之前,如果无法下笔,则先想想要写代码架子都有哪些。

办法二、一级段落不要超过5个。
这纯粹是个经验值,实际超过3个的时候已经开始有些遗忘前面的了。套在代码上,不要超过5种主要功能的目录,像nginx有6个,不过os和misc基本上都是固定不改的东西,所以常动的也只有4个而已。

办法三、不要没有段落画大饼
这和办法二是相反的,因为人脑对内容的吸收是有阶梯的,越往后的内容越难记住。所以在适当的时候要歇一歇。套在代码上,就是不要搞一个大类,什么都能干。

办法四、尽可能让文档(代码)先少后多
这个办法是指,让读代码的人先看一小部分,慢慢再“勾引”读者不断地深入。

了,上面的办法都实施之后,一手好湿就应该不远了。


原创文章如转载,请注明:转载自五四陈科学院[http://www.54chen.com]
本文链接: http://www.54chen.com/architecture/how-to-document-code.html

This entry was posted in 架构研究 and tagged . Bookmark the permalink.

Leave a Reply