嵌入式开发不用写文档?

描述

最近看到有交流群在讨论:嵌入式开发到底要不要写文档的话题。

这个话题要展开讨论的话,可能要分很多种情况,公司规模、项目难度、管理制度。。。

分享正文之前,给大家推荐一些嵌入式相关的职位:

俗话说,不会写文档的工程师不是好的工程师!

如果你只会写代码,而从不写文档,你可能只适合中午写代码,因为早晚会“出事”。

不写文档有什么后果?

如果不写文档,开发过程中就会出现类似下面这些情况。

领导:这个功能不好、再添加一个功能、把这个功能去掉等。

软件:这个功能不能实现、代码只能重构、一个bug引发N个bug等。

硬件:添加功能只能重新画板、没有考虑要预留通信接口等。

通常,在小公司不写设计文档很正常,但是隐患很大。反复增删功能、调整方案这都需要付出大量时间和精力。

只是一两次小改动都还好,如果多次、大改动的话,就会出现互相甩锅、同事不和的后果。

不要问为什么,经历过的人都懂

嵌入式项目,需要哪些设计文档?

我之前参与开发的项目,从需求、设计、实现、测试、总结等这几个阶段下来,设计文档多的时候有上100个文档。

当然,这里面是包含不同岗位(软件、硬件、机械、测试等)、不同模块等细分的各种文档。

对于不同的项目,可能设计文档种类和数量不同,比如你一个简单的电子手表,可只需要一个需求文档、一个方案设计文档就可以了。

其实,项目越复杂,设计文档越多。比如京东的仓储物流这一套系统,你能想想一下有多少个设计文档吗?光是需求阶段的文档肯定都有上百个:需求、评估、审核等各种文档。

当然,对于我们普通的项目,需要的设计文档可能几个 ~ 十几个就可以了,

比如:需求文档、评估文档、总方案文档、模块方案文档、通信协议文档、测试用例文档等。

每一种文档没有固定的格式,只需要结合你自己实际项目,把重点描述清楚,能指导开发人员,方便开发和设计即可。

举例:xxx项目电源管理方案

下面分享一个简单方案设计文档。

1.封面总体

就像一个本书的封面,把主要信息罗列出来。比如:

项目名称、文档版本、日期、作者、密级等。

比如:

2.文档目录

作为一个技术开发人员,如果你连word的目录都不知道怎么生成,你应该好好反思一下了。

目录很简单,比如:

这里想说下,目录是自动生成,而不是手动编辑的目录。

我就发现有人的目录居然是手动编辑的,不知道大家是不也这么“水”?

3.引言

这里引言也可以是“概述”,把整个方案的主要内容进行描述,比如这里简单列几点:

4.框架

框架就是首先给人第一眼就能了解你这个项目有些什么东西。

比如系统框架、软、硬件框架等。这里需要用到一些设计框架的工具,比如:Visio.

比如:

5.硬件设计

罗列硬件相关的设计信息,比如硬件供电、状态等。

6.软件流程

牵涉到软件,在方案中必不可少的一点,就是软件流程。

如果你软件流程都不清楚,在开发过程中,肯定会反反复复修改代码,甚至修改了数十版不能用。

软件流程网上有很多例子可参看,比如按键检测流程:

比如电压、电流检测流程:

7.系统状态

每一个系统基本都由多个状态(或者模式),比如工作状态、空闲状态、故障状态等。

你要把系统可能遇到的状态都列出来,并描述清楚。比如:

8.通信协议、接口设计等其他

比如你的项目中会用到通信,需要把通信协议整理出来。

或者简单描述通信相关的内容,比如硬件使用了UART、CAN,通信协议使用CANopen、Modbus等。然后具体协议指令单独一个文档。(见:协议文档)。

最后,以上内容仅供参考,不同项目的情况不同。根据项目情况把设计中需要考虑的重要信息整理出来,并容易理解就可以了。

审核编辑 :李倩

打开APP阅读更多精彩内容
声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • 相关推荐

全部0条评论

快来发表一下你的评论吧 !

×
20
完善资料,
赚取积分