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

作为一个长期混迹于CSDN 区的人，我对很多拥有高访问量的博主钦佩不已，特别是在参加了CSDN在举办“2014 CSDN博文大赛”及“2015 CSDN-Markdown博文大赛”活动之后。我看到活动中的一些参赛作品条理清晰、文笔流畅、语言优美，大都出自程序员之手。我不禁想到一个问题：程序员是否应该注重文档的编写/p>

写文档的重要性

对于软件相关行业，在学校或单位大家也许都已经注意到了，除了要编写的程序、绘制设计图之外，还有一个重要的工作便是写文档。为什么要写文档呢 为我们要把自己做的东西展示出来，不光展示给同行看，可能还要展示给其他岗位上的工作人员看，甚至展示给用户看。如果我们只是会写程序，不会在文档中恰当 且优雅地描述自己的想法，那么就真正的成为“码农”了。

我注意了一下，周围的同事会写高质量文档的确实很少。李开复老师在《浪潮之巅》的序言中说到：“我认识很多顶尖的工程师，但具备强大叙事能力的优秀工程师，我认识的可以说是凤毛麟角。”确实，我所认识的同事，能够在文档中清晰地表达自己想法的也很少。

有关文档书写，我印象很深的问题有如下几个方面：

有关计算机软件的传统定义为：软件是计算机系统中与硬件相依存的另一部分，软件包括程序、数据及其相关文档的完整集合。注意，这里面就提到了“相关文档”，如果文档没有写好，那么软件也不能算是优秀的软件。事实上，软件功能健全，而由于文档原因出现故障的情况还时有发生。

一般说来，在软件开发过程中，不同阶段涉及到的主要文档如下图所示：

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

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

例如，有下面一段描述：

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

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

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

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

也许是为了省事，很多程序员喜欢将工程代码直接粘贴到文档中，这不仅会占用大量的文档篇幅，而且会降低文档的可读性。试想，一个从没有接触过代码的 人，如何能够看懂你在文档中给出的代码使对于有经验的程序员来说，一眼看到你写出来的程序，也不见得能够一下就明白的。如果你写的代码确实很好，想给 别人看，那么在正文中可以只给出设计思想、流程图等，而在附录中给出完整的代码。

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

其它一些建议

1.改变文档为辅的观念，在平常的工作中，对于自己编写的每一份文档，均认真对待。
2.对于邮件的编写，要把自己想说的话准确地表达出来，在发送邮件之前，再看一下内容是否完整、是否还有错别字、语句是否通顺等。
3.在编写文档的过程中，要严格参照项目组规定的模板来完成。在写完文档之后，对文档进行语法检查，以纠正错别字和有语法错误的地方。一般说来，有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前，再通读一下整个文档，看是否还有疏漏和不足。
4.在工作之余，可以读一些能够提高语言表达能力和写作能力的书籍或文章，看一下别人是怎样清晰地阐述自己思想的。例如，经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。

总结

要想做好一件事情，需要我们从各个方面来努力。在开发软件的过程中，写好代码很重要，清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂，一定要让两者均衡发展，而不能够只顾其一。