程序员要面对的不仅是代码,还有文档

开发 开发工具
“代码”和“文档”就像是一个人的左膀右臂,一定要让两者均衡发展,而不能够只顾其一。既然文档这么的重要,那么对于程序员来说,我们如何才能写出一份好的文档呢?

在实际的软件开发工作中,除了编写代码之外,程序员还会花大量的时间来编写相关的研发文档,这些文档包括:详细设计文档、单元/集成/系统测试文档、软件版本开发报告、软件安装说明、软件升级指导书、软件使用手册等。我认为:“代码”和“文档”就像是一个人的左膀右臂,一定要让两者均衡发展,而不能够只顾其一。既然文档这么的重要,那么对于程序员来说,我们如何才能写出一份好的文档呢?

[[215533]]

根据我个人的经验,我们不妨从以下方面入手:

***,将重要的内容分点描述,而不是杂糅在一起。

例如,有一段描述某软件功能的话是这样的:

该软件模块在系统中占有重要的地位,它从客户提供的FTP目录下获取文件,并下载到本地的目录中。接着,它扫描本地目录,对读取到的文件的内容进行解析,并生成新的文件放到本地的另一目录中。然后,它将该目录中的文件上传到客户指定的FTP目录中。对于本地目录中的文件,该模块有一个过期清理的机制,清理时间及过期期限可配置。

我们可以看到,上面那段话将软件功能描述放到一个段落中,读起来让读者云里雾里的。

我们可以把内容分点描述,如下:

  1. 该软件模块在系统中占有重要的地位,其实现的主要功能为:
  2. 从客户提供的FTP目录中下载文件到本地的目录中。
  3. 从本地目录中获取文件进行解析,并生成新的文件放到本地的另一目录中。
  4. 将目录中生成的文件上传到客户指定的FTP目录中。
  5. 清理本地目录中的过期文件(清理时间及过期期限可配置)。

这样修改之后,文章的逻辑更加的清晰,可读性更强,读者也更容易理解作者所要表达的意思。

第二,将流程性比较强的内容画成流程图,而不是仅用文字描述。

一篇图文并茂的文章才是好文章,如果大家看到一篇好几十页的文章全是文字,很容易失去阅读的兴趣。对于某些流程性比较强的内容,如果将文字变成流程图,则给读者的感觉是不一样的。

例如,下面一段文字描述了socket的整个消息流程:

  • ***步,创建socket。
  • 第二步,绑定指定的IP地址和端口。如果绑定失败,则跳到***步。
  • 第三步,启动监听。如果没有监听到消息,则程序一直处于监听状态;如果监听到了消息,则执行下一步。
  • 第四步,循环从监听队列中获取消息,并根据消息内容执行相关的操作。

将文字内容画成流程图,如下所示:

从流程图中,我们更容易看出程序的逻辑,让读者在一段轻松的阅读旅程中理解作者所要表达的意思。

第三,将带数字的内容以图表的形式呈现,而非用文字描述。

对于某些有参照性质的数字,我们可以用图表的形式来呈现,这样可以让读者看到相邻几组数字的变化情况,文章的表达效果更好。

例如,有下面一段描述:

今年3月份,解决的软件bug数量为8;今年4月份,解决的软件bug数量为6;今年5月份,解决的软件bug数量为10。

可以将以上内容替换成下面的图表:

从图中,我们更容易看出前后数字的变化情况,对所描述事物有一个整体的把握。

第四,尽量不要直接在文档中贴代码,而换之以伪代码、流程图等形式。

也许是为了省事,很多程序员喜欢将工程代码直接粘贴到文档中,这不仅会占用大量的文档篇幅,而且会降低文档的可读性。试想,一个从没有接触过代码的人,如何能够看懂你在文档中给出的代码?即使对于有经验的程序员来说,一眼看到你写出来的程序,也不见得能够一下就明白的。

如果你写的代码确实很好,想给别人看,那么在正文中可以只给出设计思想、流程图等,而在附录中给出完整的代码。

以上几点写文档的建议是本人在写文档过程中的一些心得体会,不见得都正确,大家可以参考。总的说来,文档的编写要遵循简单易懂的原则,要用最直接明了的方式来表达作者本人的意思。

爱因斯坦曾说过:“科学家应该使用最简单的手段达到他们的结论,并排除一切不能被认识到的事物”。也就是说,简单就是美。这个“简单”的原则同样可以应用到文档编写中,应用到所有的软件开发项目中。

【本文是51CTO专栏作者周兆熊的原创文章,作者微信公众号:周氏逻辑(logiczhou)】

戳这里,看该作者更多好文

责任编辑:赵宁宁 来源: 51CTO专栏
相关推荐

2022-12-21 17:17:24

2014-07-17 10:35:31

游戏引擎代码工具

2011-08-04 11:02:51

交换机Nexus思科

2019-03-20 20:26:41

微隔离防火墙

2009-11-05 15:53:32

无线局域网

2019-11-06 11:31:26

刷脸支付支付宝互联网

2020-08-29 18:32:21

物联网投资物联网IOT

2012-03-12 16:14:51

愤怒的小鸟太空版

2011-08-04 14:06:25

安全SOC安全运营

2014-07-21 15:23:47

隐私泄露移动安全趋势科技

2017-03-29 17:32:53

5G4G移动通信

2019-07-10 15:10:14

高性能服务器架构

2017-09-10 17:08:11

Java 9程序Oracle

2017-07-18 14:44:01

互联网智能中国智造

2022-06-16 15:36:37

攻击面管理ASM

2010-11-22 13:28:55

2011-12-06 08:44:01

程序员

2009-11-03 14:11:45

宽带接入网

2010-04-02 14:55:58

IDF2010

2016-08-09 09:22:52

英特尔Cloudera
点赞
收藏

51CTO技术栈公众号