程序员既要写好代码,又要写好文档

程序员既要写好代码,又要写好文档

作为一个长期混迹于CSDN社区的人,我对很多拥有高访问量的博主钦佩不已,特别是在参加了CSDN在举办“2014 CSDN博文大赛”及“2015 CSDN-Markdown博文大赛”活动之后。我看到活动中的一些参赛作品条理清晰、文笔流畅、语言优美,大都出自程序员之手。我不禁想到一个问题:程序员是否应该注重文档的编写? 写文档的重要性 对于软件相关行业,在学校或单位大家也许都已经注意到了,除了要编写的程序、绘制设计图之外,还有一个重要的工作便是写文档。为什么要写文档呢?因为我们要把自己做的东西展示出来,不光展示给同行看,可能还要展示给其他岗位上的工作人员看,甚至展示给用户看。如果我们只是会写程序,不会在文档中恰当且优雅地描述自己的想法,那么就真正的成为“码农”了。 我注意了一下,周围的同事会写高质量文档的确实很少。李开复老师在《浪潮之巅》的序言中说到:“我认识很多顶尖的工程师,但具备强大叙事能力的优秀工程师,我认识的可以说是凤毛麟角。”确实,我所认识的同事,能够在文档中清晰地表达自己想法的也很少。 有关文档书写,我印象很深的问题有如下几个方面: 1.我们每天都会收发很多邮件,我仔细看了一下,很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候,从不同的角度理解,一封邮件有很多不同的意思,让人感觉不知道它究竟要表达一个什么意思,这样极大地降低了工作的效率。 2.除了代码之外,项目也会包含了大量的文档。打开大部分文档,看到的第一眼,我就有这几种感觉:排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档,并且语句的表达和组织能力也不强。 3.在项目小组成员讨论的时候,大家几乎都在说怎样把程序写好,而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好,其它什么的都是其次的。 有关计算机软件的传统定义为:软件是计算机系统中与硬件相依存的另一部分,软件包括程序、数据及其相关文档的完整集合。注意,这里面就提到了“相关文档”,如果文档没有写好,那么软件也不能算是优秀的软件。事实上,软件功能健全,而由于文档原因出现故障的情况还时有发生。 一般说来,在软件开发过程中,不同阶段涉及到的主要文档如下图所示:

可见,在软件的不同阶段,需要编写不同的文档。在计划阶段,需要编写详细设计文档、单元测试方案文档和集成测试方案文档等;在开发阶段,也是这几个文档,不过是修订版,因为我们在实际开发过程中,会发现之前设计不合理的地方或者是考虑不周的地方,这就需要对之前的文档进行修改;在测试阶段,要编写单元测试报告、集成测试报告和系统测试报告等;在软件的发布阶段,要编写安装手册、用户手册、升级指导书等,这些文档主要是面向现场支持人员和用户的,因此要尽量写得通俗易懂,千万不要有模棱两可的情况存在,否则就只有等待用户的投诉了。 要想写好文档,我们需要首先纠正一个观念:文档不重要。要把文档放在与程序同等重要的位置。 程序员如何写出高质量文档? 既然文档这么的重要,那么对于程序员来说,我们如何才能写出一份好的文档呢?根据我个人的经验,我们不妨从以下方面入手: 第一,将重要的内容分点描述,而不是杂糅在一起。 例如,有一段描述某软件功能的话是这样的: 该软件模块在系统中占有重要的地位,它从客户提供的FTP目录下获取文件,并下载到本地的目录中。接着,它扫描本地目录,对读取到的文件的内容进行解析,并生成新的文件放到本地的另一目录中。然后,它将该目录中的文件上传到客户指定的FTP目录中。对于本地目录中的文件,该模块有一个过期清理的机制,清理时间及过期期限可配置。 我们可以看到,上面那段话将软件功能描述放到一个段落中,读起来让读者云里雾里的。我们可以把内容分点描述,如下: 该软件模块在系统中占有重要的地位,其实现的主要功能为: (1)从客户提供的FTP目录中下载文件到本地的目录中。 (2)从本地目录中获取文件进行解析,并生成新的文件放到本地的另一目录中。 (3)将目录中生成的文件上传到客户指定的FTP目录中。 (4)清理本地目录中的过期文件(清理时间及过期期限可配置)。 这样修改之后,文章的逻辑更加的清晰,可读性更强,读者也更容易理解作者所要表达的意思。 第二,将流程性比较强的内容画成流程图,而不是仅用文字描述。 一篇图文并茂的文章才是好文章,如果大家看到一篇好几十页的文章全是文字,很容易失去阅读的兴趣。对于某些流程性比较强的内容,如果将文字变成流程图,则给读者的感觉是不一样的。 例如,下面一段文字描述了socket的整个消息流程: 第一步,创建socket。 第二步,绑定指定的IP地址和端口。如果绑定失败,则跳到第一步。 第三步,启动监听。如果没有监听到消息,则程序一直处于监听状态;如果监听到了消息,则执行下一步。 第四步,循环从监听队列中获取消息,并根据消息内容执行相关的操作。 将文字内容画成流程图,如下所示:

从流程图中,我们更容易看出程序的逻辑,让读者在一段轻松的阅读旅程中理解作者所要表达的意思。 第三,将带数字的内容以图表的形式呈现,而非用文字描述。 对于某些有参照性质的数字,我们可以用图表的形式来呈现,这样可以让读者看到相邻几组数字的变化情况,文章的表达效果更好。 例如,有下面一段描述: 今年3月份,解决的软件bug数量为8;今年4月份,解决的软件bug数量为6;今年5月份,解决的软件bug数量为10。 可以将以上内容替换成下面的图表:

从图中,我们更容易看出前后数字的变化情况,对所描述事物有一个整体的把握。 第四,尽量不要直接在文档中贴代码,而换之以伪代码、流程图等形式。 也许是为了省事,很多程序员喜欢将工程代码直接粘贴到文档中,这不仅会占用大量的文档篇幅,而且会降低文档的可读性。试想,一个从没有接触过代码的人,如何能够看懂你在文档中给出的代码?即使对于有经验的程序员来说,一眼看到你写出来的程序,也不见得能够一下就明白的。如果你写的代码确实很好,想给别人看,那么在正文中可以只给出设计思想、流程图等,而在附录中给出完整的代码。 以上几点写文档的建议是本人在写文档过程中的一些心得体会,不见得都正确,大家可以参考。总的说来,文档的编写要遵循简单易懂的原则,要用最直接明了的方式来表达作者本人的意思。 爱因斯坦曾说过:“科学家应该使用最简单的手段达到他们的结论,并排除一切不能被认识到的事物”。也就是说,简单就是美。这个“简单”的原则同样可以应用到文档编写中,应用到所有的软件开发项目中。 其它一些建议 1.改变文档为辅的观念,在平常的工作中,对于自己编写的每一份文档,均认真对待。 2.对于邮件的编写,要把自己想说的话准确地表达出来,在发送邮件之前,再看一下内容是否完整、是否还有错别字、语句是否通顺等。 3.在编写文档的过程中,要严格参照项目组规定的模板来完成。在写完文档之后,对文档进行语法检查,以纠正错别字和有语法错误的地方。一般说来,有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前,再通读一下整个文档,看是否还有疏漏和不足。 4.在工作之余,可以读一些能够提高语言表达能力和写作能力的书籍或文章,看一下别人是怎样清晰地阐述自己思想的。例如,经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。 总结 总的说来,和做其它事情一样,书写文档也反映了一个人的态度问题。写出高质量的文档,不仅可以提升个人的形象(如果你看到一篇好文档,是不是也对作者有较高的评价?),还能够提升产品在客户心中的形象。如此分析,多花些心思来书写文档真的是很有必要。 要想做好一件事情,需要我们从各个方面来努力。在开发软件的过程中,写好代码很重要,清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂,一定要让两者均衡发展,而不能够只顾其一。

原文发布于微信公众号 - Java学习网(javalearns)

原文发表时间:2015-10-21

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏腾讯云安全的专栏

授权登录的安全短板——[移动 APP 安全揭秘]第二期

19640
来自专栏顶级程序员

这8点能教你如何更好地阅读代码

译者:Tocy, 亚林瓜子, 总长 出处:开源中国 链接:https://www.oschina.net/translate/how-to-read-code...

45980
来自专栏Rainbond开源「容器云平台」

微服务的误读与误解

16450
来自专栏美团技术团队

【技术博客】使用模板快速编写测试用例

在高速发展的互联网公司,由于产品的开发迭代太快,产品测试经常遇到以下几个问题: 如何在快速的产品开发迭代中迅速地完成对产品功能的测试? 面对用户众多、环境多样,...

63290
来自专栏CSDN技术头条

微服务的误读与误解

微服务确实很受欢迎,但是对于微服务的误解也是事实,本文对这些误解一一来介绍下: 一、微服务不够“微”? 尽管微服务定义的很明确,但是开发者社区对它的解释却颇有争...

204100
来自专栏互联网高可用架构

互联网性能与容量评估的方法论和典型案例5 性能评估参考标准

62840
来自专栏FreeBuf

安全专家说Android 8.0和iPhone X一样安全,这是真的吗?

Android 这两年的甜点代号越来越腻味,上个月 Android 8.0,以代号 Oreo(奥利奥)的方式问世了,奥利奥感觉比牛轧糖、棉花糖之类的都要甜。可能...

26590
来自专栏移动安全

APP加固方案需稳定与安全并重

很多开发者没有意识到APP的安全隐患可能会严重损害他们的利益,加固可以帮助他们规避很多风险;

8K90
来自专栏ThoughtWorks

系统级集成测试的断舍离|洞见

食之无味,弃之可惜 在企业级应用的“季度或月度发布”被认为是领域最佳实践的时候,在应用部署到生产环境之前维护一个完整的环境来进行集成测试是非常必要的。但是,集成...

30190
来自专栏微信小开发

微信又出新功能了:以前没发挥好的,咱再来一次

想必大家伙都知道 微信又更新了吧~ 微信更新可谓是家常便饭 除了上次更新朋友圈设置“允许朋友查看朋友圈范围” ? 以及在6姐微信里消失的无影无踪的 “不常联系朋...

284100

扫码关注云+社区

领取腾讯云代金券