|
|
|
|
移动端
创建专栏

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

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

作者:周兆熊|2018-01-01 07:04

开发者盛宴来袭!7月28日51CTO首届开发者大赛决赛带来技术创新分享

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

例如,有下面一段描述:

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

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

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

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

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

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

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

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

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

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

【编辑推荐】

  1. 程序员如何不被淘汰?一定要看11月的这十篇热门文章!
  2. 油腻代码大叔与蝴蝶效应
  3. 后端程序员都做些什么?
  4. 你写的代码,是别人的噩梦吗?
  5. 2018,程序员做好这11件事,必拿高薪!
【责任编辑:赵宁宁 TEL:(010)68476606】

点赞 0
分享:
大家都在看
猜你喜欢

热门职位+更多