|
| |
|
|
| |
| 2.1 写文档时的出发点 |
写文档的目的是为了让别人能看懂，帮助以后的人员或自己能够很好的维护程序。所以在写文档时，要注意，做到简练，不要用长句子。
原则：
√句子简练，不用长句子，最好不要超过20个字
√每页要有图或表，特别在写设计文档时，绝对要有图
√信息量要足够，在别人看文档时，如果经常来问你的话，说明文档没有写好
养成习惯：
每次在写文档时，想一想自己写的文档是否其他人能看懂，信息量是否足够。
以下是从一篇交换机设计文档中抽取出来的2个例子，可以看到信息量不足时的情况。
例子1
---------------开始---------------
5．循环中：监听口有返回，则接收到相应结构中，判断FLAG＝1，则进行定时器链表遍历，先看头一个定时器的绝对时间是否小于当前时间，如果小于则说明所以定时器均未超时，跳出处理程序，进行下一个循环。如果大于等于当前时间，则调用超时处理函数。处理后判断下一个定时器是否超时，并相应处理直到下一个定时器不超时退出处理程序，进行下一个循环。
---------------结束---------------
从该文章中，可以看到全是用语言在描述一个流程，当你看到这种文章时，肯定要在脑子里走流程，不聪明的，走到一半就得放弃了！实际上很简单，画一个示意图就可以让人一看就懂。
例子2
---------------开始---------------
12．数据构件的关系结构 |
|
13．通话结束后，涉及到：CCD的HASH表清0（共享内存和HASH表同时修改），CCD的未用管理链表加入，对应TimerID定时器清除，对应RTPPortID清除，CCB的HASH表清0，CCB的未用管理链表加入，CCB所在共享内存清0。
---------------结束---------------
这里的问题是画了图，却不对图中的内容作出说明。让看的人不知道图中要说明的是何意。另外”13”一项的说明也是写法不清楚，没有条理。可以写成，在结束通话时，需要做的结束处理1，2，3，可能更加有条理。 |
|
|
|
