嵌入式开发不用写文档?
关注+星标公众号,不错过精彩内容
作者 | strongerHuang
微信公众号 | strongerHuang
最近看到有交流群在讨论:嵌入式开发到底要不要写文档的话题。
这个话题要展开讨论的话,可能要分很多种情况,公司规模、项目难度、管理制度。。。
分享正文之前,给大家推荐一些嵌入式相关的职位:
俗话说,不会写文档的工程师不是好的工程师!
如果你只会写代码,而从不写文档,你可能只适合中午写代码,因为早晚会“出事”。
不写文档有什么后果?
如果不写文档,开发过程中就会出现类似下面这些情况。
领导:这个功能不好、再添加一个功能、把这个功能去掉等。
软件:这个功能不能实现、代码只能重构、一个bug引发N个bug等。
硬件:添加功能只能重新画板、没有考虑要预留通信接口等。
通常,在小公司不写设计文档很正常,但是隐患很大。反复增删功能、调整方案这都需要付出大量时间和精力。
只是一两次小改动都还好,如果多次、大改动的话,就会出现互相甩锅、同事不和的后果。
不要问为什么,经历过的人都懂
嵌入式项目,需要哪些设计文档?
我之前参与开发的项目,从需求、设计、实现、测试、总结等这几个阶段下来,设计文档多的时候有上100个文档。
当然,这里面是包含不同岗位(软件、硬件、机械、测试等)、不同模块等细分的各种文档。
对于不同的项目,可能设计文档种类和数量不同,比如你一个简单的电子手表,可只需要一个需求文档、一个方案设计文档就可以了。
其实,项目越复杂,设计文档越多。比如京东的仓储物流这一套系统,你能想想一下有多少个设计文档吗?光是需求阶段的文档肯定都有上百个:需求、评估、审核等各种文档。
当然,对于我们普通的项目,需要的设计文档可能几个 ~ 十几个就可以了,
比如:需求文档、评估文档、总方案文档、模块方案文档、通信协议文档、测试用例文档等。
每一种文档没有固定的格式,只需要结合你自己实际项目,把重点描述清楚,能指导开发人员,方便开发和设计即可。
举例:xxx项目电源管理方案
下面分享一个简单方案设计文档。
1.封面总体
就像一个本书的封面,把主要信息罗列出来。比如:
项目名称、文档版本、日期、作者、密级等。
比如:
2.文档目录
作为一个技术开发人员,如果你连word的目录都不知道怎么生成,你应该好好反思一下了。
目录很简单,比如:
这里想说下,目录是自动生成,而不是手动编辑的目录。
我就发现有人的目录居然是手动编辑的,不知道大家是不也这么“水”?
3.引言
这里引言也可以是“概述”,把整个方案的主要内容进行描述,比如这里简单列几点:
4.框架
框架就是首先给人第一眼就能了解你这个项目有些什么东西。
比如系统框架、软、硬件框架等。这里需要用到一些设计框架的工具,比如:Visio.
比如:
5.硬件设计
罗列硬件相关的设计信息,比如硬件供电、状态等。
6.软件流程
牵涉到软件,在方案中必不可少的一点,就是软件流程。
如果你软件流程都不清楚,在开发过程中,肯定会反反复复修改代码,甚至修改了数十版不能用。
软件流程网上有很多例子可参看,比如按键检测流程:
比如电压、电流检测流程:
7.系统状态
每一个系统基本都由多个状态(或者模式),比如工作状态、空闲状态、故障状态等。
你要把系统可能遇到的状态都列出来,并描述清楚。比如:
8.通信协议、接口设计等其他
比如你的项目中会用到通信,需要把通信协议整理出来。
或者简单描述通信相关的内容,比如硬件使用了UART、CAN,通信协议使用CANopen、Modbus等。然后具体协议指令单独一个文档。(见:协议文档)。
最后,以上内容仅供参考,不同项目的情况不同。根据项目情况把设计中需要考虑的重要信息整理出来,并容易理解就可以了。
------------ END ------------
●专栏《嵌入式工具》
●专栏《嵌入式开发》
●专栏《Keil教程》
●嵌入式专栏精选教程
关注公众号回复“加群”按规则加入技术交流群,回复“1024”查看更多内容。
点击“阅读原文”查看更多分享。
嵌入式开发不用写文档?相关推荐
- java开发文档怎么写_程序员该不该写技术文档,怎么写文档,易懂又能提升自己...
最近公司项目的调用量突然涨了一大波,很多系统都纷纷扛不住了,于是需要对系统进行优化,系统优化的第一步,便是梳理业务! 在这个过程中,经常出现了这样一些情况,发现数据库的某些字段,没有注释,也没有一定的 ...
- 比Word更优雅的记笔记/写文档/交报告方式
比Word更优雅的记笔记/写文档/交报告方式 markdown+vscode->pdf 背景 最近在上的一门<信息系统开发工具>课老师要求实验以后都要交实验报告,但是和以往不同的是, ...
- 老油条用什么工具写文档?
写代码,哪个程序员都不害怕. 写文档,哪个程序员都害怕! 为什么? 还不是因为 API 工具不好使,不便捷,同步麻烦,测试看不懂-- 最近调研了身边一些开发团队,发现他们列举的工具中,都出现过同一款工 ...
- SpringMvc集成Springfox使用Swagger写文档和测试
SpringMvc集成Springfox使用Swagger写文档和测试 前言 swagger简介 swagger确实是个好东西,可以跟据业务代码自动生成相关的api接口文档,尤其用于restful风格 ...
- 为什么程序员都不写文档?
[CSDN 编者按]对于程序员来说文档可能是他最大的软肋.一些被称之为高手的程序员,往往是文档方面的处理会偏弱.不管这个程序员是在大公司.还在小公司.不管程序是写文档的.还是不写文档的,大 ...
- 如何理解写文档这件事情 ?
目录 目录 前言 对公司而言 标准化流程 最佳实践 对自己而言 前言 个人札记, 写下对 写文档 这件事情的理解, 欢迎讨论. 对公司而言 文档系统是 标准化流程 和 最佳实践 的温床. 我们不仅是在 ...
- 程序员都讨厌写文档?这4个工具让你事半功倍
长按识别上方二维码,关注公众号:后端面试那些事 回复"报告",获取你的GitHub年度报告! 对于一般的程序员来说,花费数小时来创建代码或修改现有代码只是一天工作中的一部分,简而言 ...
- python如何读取公共盘的文档_如何使用 Sphinx 给 Python 代码写文档 | Linux 中国
最好将文档作为开发过程的一部分.Sphinx 加上 Tox,让文档可以轻松书写,并且外观漂亮.-- Moshe Zadka Python 代码可以在源码中包含文档.这种方式默认依靠 docstring ...
- python代码_如何使用 Sphinx 给 Python 代码写文档
最好将文档作为开发过程的一部分.Sphinx 加上 Tox,让文档可以轻松书写,并且外观漂亮.-- Moshe Zadka(作者) Python 代码可以在源码中包含文档.这种方式默认依靠 docst ...
最新文章
- 最新的SCI-HUB访问地址
- 使用Ultra Librarian转换芯片的Altium Designer封装格式
- 3D目标检测 CVPR2020 总结
- 第11章 Internet 服务器应用课后习题答案
- 工作294:for[item.key]使用
- Linux学习笔记(五)
- 上海建桥学院linux网络管理实验报告,上海建桥学院信息技术系《操作系统(Linux).PDF...
- httpcline转发_go http请求转发
- 一部分 数据 迁移_11项最佳实践,每次数据中心迁移都必不可少
- 全网首发:JDK绘制文字:五、字体上下文产生流程
- 人大金仓数据库(kingbase7d)操作入门指南
- 机器人学习笔记(3) 正运动学和逆运动学
- 无纸化会议系统服务器是什么意思,无纸化会议系统是什么?
- linux xps文件,Master PDF:PDF和XPS文件编辑神器
- java的create vm_JNI_CreateJavaVM(Runtime::Create())
- 测试数据生成工具datafaker
- Vim实用技巧_7.模式匹配和查找
- DevExpress VCL Subscription 版本:21.1.5
- JAVA设计模式详解(四)----------适配器模式
- 【Android 进阶】开发APP常见的错误