青年文摘在线订阅网

来源：蜘蛛抓取(WebSpider) 时间：2017-10-11 01:31 标签： 哪些杂志适合新手投稿
【畅言】程序员既要写好代码，又要写好文档
发表于 07:43|
作者周兆熊
摘要：程序员是否应该注重文档的编写？这是一个看似很小但却比较重要的问题。软件除了程序和数据外，还包括文档。其次，如果程序员只是会写程序，不能在文档中恰当且优雅地描述自己的想法，那么就真的是“码农”了。
最近，CSDN在举办“2014 CSDN博文大赛”活动。我看本次活动中的一些参赛作品条理清晰、文笔流畅、语言优美，大都出自程序员之手。我不禁想到一个问题：程序员是否应该注重文档的编写？写文档的重要性对于软件相关行业，在学校或单位大家也许都已经注意到了，除了要编写的程序、绘制设计图之外，还有一个重要的工作便是写文档。为什么要写文档呢？因为我们要把自己做的东西展示出来，不光展示给同行看，可能还要展示给其他岗位上的工作人员看，甚至展示给用户看。如果我们只是会写程序，不会在文档中恰当且优雅地描述自己的想法，那么就真正的成为“码农”了。我注意了一下，周围的同事会写高质量文档的确实很少。李开复老师在《浪潮之巅》的序言中说到：“我认识很多顶尖的工程师，但具备强大叙事能力的优秀工程师，我认识的可以说是凤毛麟角。”确实，我所认识的同事，能够在文档中清晰地表达自己想法的也很少。有关文档书写，我印象很深的问题有如下几个方面：我们每天都会收发很多邮件，我仔细看了一下，很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候，从不同的角度理解，一封邮件有很多不同的意思，让人感觉不知道它究竟要表达一个什么意思，这样极大地降低了工作的效率。除了代码之外，项目也会包含了大量的文档。打开大部分文档，看到的第一眼，我就有这几种感觉：排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档，并且语句的表达和组织能力也不强。在项目小组成员讨论的时候，大家几乎都在说怎样把程序写好，而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好，其它什么的都是其次的。有关计算机软件的传统定义为：软件是计算机系统中与硬件相依存的另一部分，软件包括程序、数据及其相关文档的完整集合。注意，这里面就提到了“相关文档”，如果文档没有写好，那么软件也不能算是优秀的软件。事实上，软件功能健全，而由于文档原因出现故障的情况还时有发生。一般说来，在软件开发过程中，不同阶段涉及到的主要文档如下图所示：可见，在软件的不同阶段，需要编写不同的文档。在计划阶段，需要编写详细设计文档、单元测试方案文档和集成测试方案文档等；在开发阶段，也是这几个文档，不过是修订版，因为我们在实际开发过程中，会发现之前设计不合理的地方或者是考虑不周的地方，这就需要对之前的文档进行修改；在测试阶段，要编写单元测试报告、集成测试报告和系统测试报告等；在软件的发布阶段，要编写安装手册、用户手册、升级指导书等，这些文档主要是面向现场支持人员和用户的，因此要尽量写得通俗易懂，千万不要有模棱两可的情况存在，否则就只有等待用户的投诉了。要想写好文档，我们需要首先纠正一个观念：文档不重要。要把文档放在与程序同等重要的位置。如何写出高质量文档？那么，我们如何才能写出高质量的文档呢？我认为可以从如下几个方面着手：改变文档为辅的观念，在平常的工作中，对于自己编写的每一份文档，均认真对待。对于邮件的编写，要把自己想说的话准确地表达出来，在发送邮件之前，再看一下内容是否完整、是否还有错别字、语句是否通顺等。在编写文档的过程中，要严格参照项目组规定的模板来完成。在写完文档之后，对文档进行语法检查，以纠正错别字和有语法错误的地方。一般说来，有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前，再通读一下整个文档，看是否还有疏漏和不足。在工作之余，可以读一些能够提高语言表达能力和写作能力的书籍或文章，看一下别人是怎样清晰地阐述自己思想的。例如，经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。总的说来，和做其它事情一样，书写文档也反映了一个人的态度问题。写出高质量的文档，不仅可以提升个人的形象（如果你看到一篇好文档，是不是也对作者有较高的评价？），还能够提升产品在客户心中的形象。如此分析，多花些心思来书写文档真的是很有必要。要想做好一件事情，需要我们从各个方面来努力。在开发软件的过程中，写好代码很重要，清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂，一定要让两者均衡发展，而不能够只顾其一。作者介绍：周兆熊，重庆潼南人。2009年7月毕业于海南大学通信工程专业，2012年4月毕业于南京邮电大学计算机应用技术专业，获工学硕士学位。现在中兴通讯股份有限公司重庆研发中心从事软件开发工作。微博：@周兆熊，微信：。《畅言》第十二期：【[】软件工程基于思维承载之物的特质，必然会有清晰的适用边界。但实际上恰恰与此相反，每当一种工程方法出世的时候，它的作用总是潜在的有扩大的趋势，似乎一旦锤子在手之后，所有身边的东西就都变成了应锤一锤的钉子。《畅言》第十三期：【】自然界中存在许多规律，那么在程序人生上是否有规律可循呢？这种规律是如大多数人期望的那样吗？V众投发起人李智勇对此进行了探讨，他分析了必然与偶然、本质与细节，并就程序人生规律的三要素进行了解读。《畅言》第十四期：【】应不应该禁止员工上网？这虽然是个其傻无比的问题，但仍然有公司去实践，尤其是做传统软件、外包、电信的更容易选择封杀堵截。这样无非是两个原因，一个是信息安全，一个是希望提高效率。然而其所来的危害很大。《畅言》是CSDN新栏目，供大家各抒己见。只要你看完CSDN文章或评论后有话说，都可以通过电子邮件（）投稿，从而获得上CSDN首页表达自己观点、想法的机会。《畅言》不怕观点“雷人”，只要你逻辑表达清楚、数据引用可靠，你敢投稿，我们就敢首页！欢迎大家畅所欲言。
推荐阅读相关主题：
CSDN官方微信
扫描二维码,向CSDN吐槽
微信号：CSDNnews
相关热门文章问下 代码说明文档应该怎么写的？_java吧_百度贴吧
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&签到排名：今日本吧第个签到，本吧因你更精彩，明天继续来努力！
本吧签到人数：0成为超级会员，使用一键签到本月漏签0次！成为超级会员，赠送8张补签卡连续签到：天&&累计签到：天超级会员单次开通12个月以上，赠送连续签到卡3张
关注：579,266贴子：
问下 代码说明文档应该怎么写的？收藏
弄完了一个项目
经理让我写代码说明文档我查了下 代码说明文档是要把全部的类和方法之间的关系列出来。。项目有几百个方法
几十个实体类
真列出来我觉得真不大现实你们是怎么写代码说明文档的呢？
兄弟连java入门在线学习,有多年经验的前端开发工程师授课 所有教程全部免费相关教程{html5}/CSS/JS/jQuery/BootStrap等前端课程
用javadoc　　　-- 是无法完全理解别人的，连是否理解自己都值得怀疑。要100%相互理解是不可能的，所以人才会努力让别人了解自己，也因此人生才会有趣
源代码说明书有没有模板怎么写哦
登录百度帐号推荐应用
为兴趣而生，贴吧更懂你。或

我要回帖

更多关于 哪些杂志适合新手投稿 的文章

 

随机推荐