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

先自我介绍一下,小编浙江大学毕业,去过华为、字节跳动等大厂,目前阿里P7

深知大多数程序员,想要提升技能,往往是自己摸索成长,但自己不成体系的自学效果低效又漫长,而且极易碰到天花板技术停滞不前!

因此收集整理了一份《2024年最新Golang全套学习资料》,初衷也很简单,就是希望能够帮助到想自学提升又不知道该从何学起的朋友。
img
img
img
img
img

既有适合小白学习的零基础资料,也有适合3年以上经验的小伙伴深入学习提升的进阶课程,涵盖了95%以上Go语言开发知识点,真正体系化!

由于文件比较多,这里只是将部分目录截图出来,全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频,并且后续会持续更新

如果你需要这些资料,可以添加V获取:vip1024b (备注go)
img

正文

转载于:https://developer.aliyun.com/article/196898

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

写文档的重要性

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

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

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

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

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

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

img

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

需要这份系统化的资料的朋友,可以添加V获取:vip1024b (备注Go)
img

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

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

  • 11
    点赞
  • 11
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
技术文档程序员工作中非常重要的一部分,下面是一些建议来帮助你技术文档: 1.明确目标受众:确定你的文档是面向其他开发人员、经理、客户还是非技术人员。这有助于你选择合适的语言和术语,并确保你的文档能够满足读者的需求。 2.使用清晰简洁的语言:避免使用过于复杂的术语和缩,尽量使用通俗易懂的语言来解释技术概念。如果必须使用特定术语,确保在文档中提供清晰的解释和定义。 3.结构化和组织良好:将文档分成几个部分,例如介绍、使用指南、API文档等。使用标题、段落和列表来组织内容,以便读者可以轻松地找到所需信息。 4.提供示例代码和截图:在文档中提供具体的示例代码和截图,这有助于读者理解技术概念和步骤。确保示例代码准确、可运行,并附带适当的注释。 5.使用图表和图像:使用图表和图像来说明复杂的流程、架构或数据关系。这些图像可以帮助读者更好地理解和记忆文档中的信息。 6.更新和维护:技术文档应该与软件的版本保持同步,并定期进行更新和维护。确保删除或更新过时的信息,并添加新的功能和变更。 7.注重用户反馈:接受用户的反馈和建议,并根据需要对文档进行改进。这有助于提高文档的质量和可理解性。 最后,记住技术文档是一项技能,需要不断的实践和改进。随着经验的积累,你会变得更加熟练并能够编出高质量的技术文档

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值