在大多数软件工程师对编写、使用和维护代码的抱怨中,一个常见的问题是缺乏高质量的文档。缺乏文档有什么副作用呢?当遇到一个bug时,这个缩写是什么意思?这份文件是最新的吗?在整个职业生涯中,每个软件工程师都抱怨过文档的质量、数量或者完全缺乏文档。
高质量文档对工程组织有巨大的好处。代码和api变得更容易理解。当他们的设计目标和团队目标被清楚地陈述时,项目团队会更加专注。当步骤被清晰地列出时,手动流程更容易遵循。如果过程被清楚地记录下来,那么让新成员进入团队或代码库所花费的精力就会少得多。
但是,由于文档的好处有一定的滞后性,通常不会给作者带来直接的好处。不像测试,编写完测试用例,跑一遍就有结果。毕竟,你可能只编写了一个文档,但之后它将被阅读数百次,甚至数千次;它的初始成本将摊销给所有未来的读者。文档不仅可以随着时间的推移而扩展,而且它对组织的其他部分的扩展也很关键。它有助于回答以下的问题:
虽然文档可以带来不少好处,为什么工程师通常认为它是糟糕的?其中一个原因,正如我们提到的,是好处不是立竿见影的,特别是对作者来说。另外还有以下几点:
另外一个原因是文档被视为需要维护的额外负担,而不是使现有代码的维护更容易的东西。
写文档同样对作者也有非常大的好处:
这将减少其他用户提出的问题。对于编写文档的人来说,随着时间的推移这可能是最大的好处。如果你必须向某人解释某件事不止一次,那么记录该过程通常是有意义的。
软件工程师使用单一的、主要的编程语言来编写程序,他们仍然经常使用不同的语言来解决特定的问题。工程师可能会编写shell脚本或Python来运行命令行任务,或者他们可能会用c++编写大部分后端代码,但用Java编写一些中间件代码,等等。每种语言都是工具箱中的一种工具。
文档也应该如此:它是一种工具,用不同的语言编写,以完成特定的任务。编写文档与编写代码没有多大区别。与编程语言一样,它有规则、特定的语法和样式决定,通常是为了实现与代码中类似的目的:加强一致性、提高清晰度和避免理解错误。
文档通常与代码紧密耦合,因此应该尽可能地将其视为代码。也就是说,文档也应具有如下的属性:
工程师在编写文档时犯的一个最重要的错误是只为自己编写文档。这样做是很自然的,并且为自己编写代码并非没有价值:毕竟,你可能需要在几年后查看这些代码,并试图弄清楚你曾经的想法。或者说在团队较小的时候,大家的工作交集很大,因此也能看懂你的文档,但是随着组织的发展,问题就逐渐凸显,新人会有这不同背景,团队大了以后,工作内容开始细化,交集减少,这时候之前写的文档对他们来说可能就很难理解了。
因此在开始写作之前,应该(正式或非正式地)确定文档需要满足的受众。设计文件可能需要说服决策者。教程可能需要为完全不熟悉代码库的人提供非常明确的说明。API可能需要为该API的任何用户(无论是专家还是新手)提供完整和准确的参考信息。
好的文档不需要修饰或完善。工程师在编写文档时所犯的一个错误是认为他们需要成为更好的作者。按照这个标准,很少有软件工程师会写。记住,我们的观众站在你曾经站过的地方,但没有你新的领域知识。所以你不需要成为一个伟大的作家;你只需要找一个像你一样熟悉这个领域的人。
作为工作的一部分,工程师会编写各种不同类型的文档:设计文档、代码注释、操作文档、项目页面等等。这些都可以算作文档。但重要的是要知道不同的类型,不要混合类型。一般来说,文档应该有一个单一的目的。正如API应该做一件事并且做好一样,避免在一个文档中做几件事。
软件工程师经常需要编写几种主要类型的文档:
1.参考文档
参考文档是工程师最常编写的文档类型;事实上,他们经常需要每天写一些参考文档。代码注释是工程师必须维护的最常见的参考文档形式。这些注释可以分为两个基本阵营:API注释和实现注释。这两种用户之间的区别:API注释不需要讨论实现细节或设计决策,也不要假设用户和作者一样精通API。但是实现注释可以假定读者有更多的领域知识,但是要注意不要假设得太多。
2.设计文档
大多数公司在项目开始之前都需要有设计文档。软件工程师通常使用团队批准的特定设计文档模板来编写建议的设计文档。然后还需要在特定的团队会议上讨论或评论设计的细节。
一个好的设计文档应该涵盖:
一份优秀的设计文件,一旦获得批准,不仅可以作为历史记录,还可以作为项目是否成功实现其目标的衡量标准。大多数团队会将他们的设计文档进行归档,以便在后续的时间查看。在产品发布前检查设计文档通常是很有用的,以确保编写设计文档时所陈述的目标在发布时仍然是所陈述的目标(如果不是,那么文件或产品都可以进行相应的调整)。
3.教程
每个软件工程师,当他们加入一个新的团队时,都会想要尽可能快地跟上进度。拥有一个引导人们完成新项目设置的教程是非常有价值的。
通常情况下,编写教程的最佳时机是你第一次加入一个团队的时候。拿个记事本或其他方法做笔记,写下一路上你需要做的所有事情,假设没有领域知识或特殊的设置限制;完成之后,可能会知道在这个过程中所犯的错误和原因,然后可以编辑你的步骤,以获得更精简的教程。重要的是,写下一路上你需要做的一切;尽量不要假定任何特定的设置、权限或领域知识。
这类型的文档写作中,要求写作者尽可能站在用户的视角上思考,极力避免出现和用户的认知偏差,力争每个步骤做到明确无歧义,每两个步骤之间做到紧密衔接。
4.概念性文档
有些代码需要更深入的解释或见解,而不是仅仅通过阅读参考文档就能得到的。在这些情况下,我们需要概念性文档来提供api或系统的概述。概念性文档处理可能是API的库概述、描述服务器中数据生命周期的文档等。概念性文档是用来扩充而不是替换参考文档集的。有时候这和参考文档会有些内容重复,,但主要还是为了更深层次的说明某些问题、解释清楚某个概念。概念性文档没有必要涵盖所有边缘情况。在这种情况下,为了清晰度而牺牲一些准确性是可以接受的。概念性文件的要点在于传达理解。
概念文档是最难编写的文档形式。因此,它们通常是软件工程师工具箱中最容易被忽视的文档类型。而且还有另外一个问题,没合适的地方放,参考文档可以写代码里,落地页可以写项目主页里,概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。
概念文档需要对广泛的受众有用:无论是专家还是新手。此外,它需要强调清晰性,所以它通常需要牺牲完整性(最好留作参考)和(有时)严格的准确性。这并不是说概念性文件应该故意不准确;这只是意味着它应该关注常见的用法,而将罕见的用法或副作用留作参考文档。
在一个组织内,光靠个人去维护文档是不行的,必须得借助群体的智慧。在一个组织内部,文档的变更也应该像代码的变更一样,需要被其他人Review,以提前发现其中的问题并提升文档的质量。
技术文档得益于三种不同类型的review,每种审查都强调不同的方面:
下面的部分更多地是关于技术写作最佳实践的论述。
5W法则相信大家已经听的多了,分别是WHO, WHAT, WHEN, WHERE, WHY,这是一个广泛被用在各行各业的法则,写文档当然也不例外。
WHO:正如前面所说,文档的针对对象是谁,读者是谁。
WHAT:明确文档写作的用途,通常仅需说明文档的用途和目的就能帮你搭建起整个文档的框架。
WHEN:明确文档的创建、Review和更新日期。因为文档也有时效性,明确相关日期可以避免阅读者踩坑。
WHERE:文档应该放在哪!建议一个组织或者团队有统一的永久文档存放地址,并且有版本控制。最好是方便查找、使用和分享。
WHY:为什么要写这篇文档, 你期望读者读完后从文档中获得什么!
1.三段式文档
所有文档,文档的所有部分都有开头、中间和结尾。尽管这听起来非常愚蠢,但大多数文件通常都应该有这三个部分。不要害怕在文档中添加章节;它们将流程分解为逻辑部分,并为读者提供文档所涵盖内容的路线图。
通常开头部分代表问题,中间部分介绍推荐的解决方案,结尾部分总结结论。但这也并不以为着文档应该有三个部分,如果文档内容比较多,可以将其做更细致的拆解,可以适当增加一些冗余的信息帮助读者理解文档内容。虽然很多工程师都讨厌冗余 极力追求简洁,但写文档和写代码不同,适当的冗余反而可以帮助读者理解。
2.好文档必备的属性
好的文档通常有三个方面:完整性、准确性和清晰度。很少在同一个文档中同时获得这三种信息;例如,当你试图使文档更完整时,清晰度就会开始受到影响。如果您试图记录API的每个可能的用例,您可能会得到一个难以理解的混乱。对于编程语言来说,在所有情况下都做到完全准确(并记录所有可能的副作用)也会影响清晰度。对于其他文件,试图明确一个复杂的主题可能会微妙地影响文件的准确性;例如,您可能决定忽略概念性文档中的一些罕见的副作用,因为文档的目的是让人们熟悉API的用法,而不是提供对所有预期行为的武断概述。
在每种情况下,一个好的文档都被定义为正在执行其预期工作的文档。因此,您很少希望文档执行一项以上的工作。对于每个文档(以及每个文档类型),确定其重点并适当调整编写,写概念性文档可能不需要涵盖API的每个部分,写一个参考可能想要这个完整,但可能必须牺牲一些清晰度等。所有这些加起来就是质量,不可否认的是,质量很难精确衡量。
公平地说,对文档的处理与对测试的处理并不一定相同。对测试来讲可以进行原子测试(单元测试),并遵循规定的形式和功能。在大多数情况下,文件不能。测试可以自动化,但通常缺乏自动化文档的方案。文件必然是主观的;文档的质量不是由作者来衡量的,而是由读者来衡量的,而且通常是异步的。
最后总结下本文几个关键点:
文章浏览阅读1.8k次,点赞4次,收藏6次。python简易爬虫v1.0作者:William Ma (the_CoderWM)进阶python的首秀,大部分童鞋肯定是做个简单的爬虫吧,众所周知,爬虫需要各种各样的第三方库,例如scrapy, bs4, requests, urllib3等等。此处,我们先从最简单的爬虫开始。首先,我们需要安装两个第三方库:requests和bs4。在cmd中输入以下代码:pip install requestspip install bs4等安装成功后,就可以进入pycharm来写爬虫了。爬
文章浏览阅读2.6k次。解决方法:解决方法可以去github重新下载一个pyflakes.vim。执行如下命令git clone --recursive git://github.com/kevinw/pyflakes-vim.git然后进入git克降目录,./pyflakes-vim/ftplugin,通过如下命令将python目录下的所有文件复制到~/.vim/ftplugin目录下即可。cp -R ...._freetorn.vim
文章浏览阅读210次,点赞7次,收藏3次。本文简述了hello.c源程序的预处理、编译、汇编、链接和运行的主要过程,以及hello程序的进程管理、存储管理与I/O管理,通过hello.c这一程序周期的描述,对程序的编译、加载、运行有了初步的了解。_hit csapp
文章浏览阅读1w次,点赞2次,收藏27次。来源:机器人小妹 很多时候企业拥有重复,乏味且困难的工作流程,这些流程往往会减慢生产速度并增加运营成本。为了降低生产成本,企业别无选择,只能自动化某些功能以降低生产成本。 通过数字化..._人工智能平台
文章浏览阅读2.2k次。热加载能够在每次保存修改的代码后自动刷新 electron 应用界面,而不必每次去手动操作重新运行,这极大的提升了开发效率。安装 electron 热加载插件热加载虽然很方便,但是不是每个 electron 项目必须的,所以想要舒服的开发 electron 就只能给 electron 项目单独的安装热加载插件[electron-reloader]:// 在项目的根目录下安装 electron-reloader,国内建议使用 cnpm 代替 npmnpm install electron-relo._electron-reloader
文章浏览阅读942次。在11.0 进行定制化开发,会根据需要去掉recovery模式的一些选项 就是在device.cpp去掉一些选项就可以了。_android recovery 删除 部分菜单
文章浏览阅读2.2k次,点赞2次,收藏6次。继续上次的echart博客,由于省会流向图是从echart画廊中直接取来的。所以直接上代码<!DOCTYPE html><html><head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1,maximum-scale=1,user-scalable=no" /&_java+echart地图+物流跟踪
文章浏览阅读1.4k次。一、OSD模块简介1.1 消息封装:在OSD上发送和接收信息。cluster_messenger -与其它OSDs和monitors沟通client_messenger -与客户端沟通1.2 消息调度:Dispatcher类,主要负责消息分类1.3 工作队列:1.3.1 OpWQ: 处理ops(从客户端)和sub ops(从其他的OSD)。运行在op_tp线程池。1...._ceph 发送数据到其他副本的源码
文章浏览阅读7.9k次,点赞3次,收藏22次。一 定义这是最早出现的置换算法。该算法总是淘汰最先进入内存的页面,即选择在内存中驻留时间最久的页面予以淘汰。该算法实现简单,只需把一个进程已调入内存的页面,按先后次序链接成一个队列,并设置一个指针,称为替换指针,使它总是指向最老的页面。但该算法与进程实际运行的规律不相适应,因为在进程中,有些页面经常被访问,比如,含有全局变量、常用函数、例程等的页面,FIFO 算法并不能保证这些页面不被淘汰。这里,我_进程调度fifo算法代码
文章浏览阅读133次。rownum是oracle才有的写法,rownum在oracle中可以用于取第一条数据,或者批量写数据时限定批量写的数量等mysql取第一条数据写法SELECT * FROM t order by id LIMIT 1;oracle取第一条数据写法SELECT * FROM t where rownum =1 order by id;ok,上面是mysql和oracle取第一条数据的写法对比,不过..._mysql 替换@rownum的写法
文章浏览阅读790次,点赞3次,收藏4次。官网下载下载链接:http://www.eclipse.org/downloads/点击Download下载完成后双击运行我选择第2个,看自己需要(我选择企业级应用,如果只是单纯学习java选第一个就行)进入下一步后选择jre和安装路径修改jvm/jre的时候也可以选择本地的(点后面的文件夹进去),但是我们没有11版本的,所以还是用他的吧选择接受安装中安装过程中如果有其他界面弹出就点accept就行..._ecjelm
文章浏览阅读245次。原文链接:https://linux.cn/article-7801-1.htmlifconfigping <IP地址>:发送ICMP echo消息到某个主机traceroute <IP地址>:用于跟踪IP包的路由路由:netstat -r: 打印路由表route add :添加静态路由路径routed:控制动态路由的BSD守护程序。运行RIP路由协议gat..._ifconfig 删除vlan