程序员既要写好代码，又要写好文档_写文档没有用直接用代码写可以吗

2401_84904308

于 2024-05-13 14:27:03 发布

阅读量600

点赞数 14

分类专栏：程序员文章标签： go 学习面试

本文链接：https://blog.csdn.net/2401_84904308/article/details/138801784

版权

程序员专栏收录该内容

60 篇文章 1 订阅

订阅专栏

网上学习资料一大堆，但如果学到的知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。

需要这份系统化的资料的朋友，可以添加戳这里获取

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

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

1.我们每天都会收发很多邮件，我仔细看了一下，很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候，从不同的角度理解，一封邮件有很多不同的意思，让人感觉不知道它究竟要表达一个什么意思，这样极大地降低了工作的效率。
2.除了代码之外，项目也会包含了大量的文档。打开大部分文档，看到的第一眼，我就有这几种感觉：排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档，并且语句的表达和组织能力也不强。
3.在项目小组成员讨论的时候，大家几乎都在说怎样把程序写好，而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好，其它什么的都是其次的。

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

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

可见，在软件的不同阶段，需要编写不同的文档。在计划阶段，需要编写详细设计文档、单元测试方案文档和集成测试方案文档等；在开发阶段，也是这几个文档，不过是修订版，因为我们在实际开发过程中，会发现之前设计不合理的地方或者是考虑不周的地方，这就需要对之前的文档进行修改；在测试阶段，要编写单元测试报告、集成测试报告和系统测试报告等；在软件的发布阶段，要编写安装手册、用户手册、升级指导书等，这些文档主要是面向现场支持人员和用户的，因此要尽量写得通俗易懂，千万不要有模棱两可的情况存在，否则就只有等待用户的投诉了。

要想写好文档，我们需要首先纠正一个观念：文档不重要。要把文档放在与程序同等重要的位置。

程序员如何写出高质量文档？

既然文档这么的重要，那么对于程序员来说，我们如何才能写出一份好的文档呢？根据我个人的经验，我们不妨从以下方面入手：

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

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

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

我们可以看到，上面那段话将软件功能描述放到一个段落中，读起来让读者云里雾里的。我们可以把内容分点描述，如下：

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

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

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

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

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