软件能力提升记录---技术文档_软件平台能力提升-CSDN博客

本文链接：https://blog.csdn.net/quanquanxiaobu/article/details/110621308

为什么要写这篇

工作之余的时间不多，任何一点儿小的能力提升都可以被记录下来。

从真正意识到自己已经成为一名嵌入式软件工程师后的一个多月，一直在致力于提升自己的软件能力，C语言掌握能力，代码规范，注释规范，markdown工程说明，功能流程图。用尽一切自己可以接触到的方法。书籍，微信公众号，博客倒是没怎么看，也努力做着记录，虽然没有都写成博客，但之后肯定会进行补充。

这五者之间的联系是从微观到宏观，对于函数的实现方式依赖于C语言掌握能力，代码规范使得程序可读性可复用性提高，注释规范不只是函数的注释，还包含功能模块的文件头注释，功能流程图是功能的实现流程，markdown文档是工程的文档。

说起技术文档，应该追溯到我写的RGB灯的功能模块，模块里面因为函数调用关系分为外部调用和内部调用，为了将内部实现逻辑描述清楚需要函数调用关系，曾经在文件头注释中作过努力，在函数注释上作过努力，还曾经写文档记录：关于函数调用关系，关于蓝牙报文协议(发送端与接收端的字节含义约定)，关于报文举例。虽然写得一团浆糊，但应该坚持，就像画漫画一样，一开始自己画得完全与美不沾边，但坚持下去，会越来越好的。此处忍不住附图一幅，见笑。

代码规范

先提下和代码规范有点儿关系的代码格式化吧，就是一些空格、缩进之类的，影响代码阅读，本来该是一种程序员编程习惯，但代码已经那样了，总要想办法弥补一下，有个软件叫Astyle。官网下载：Astyle 下载据我实际使用，可以在Keil上配置，也可以在VScode中配置。

说下有多渴望自己写的代码规范吧。让我印象很深刻的是项目工程，两个全局变量，多个源文件调用，还是很重要的数据，导致花了挺长时间才理出头绪来，这让我想到了之前编写的不堪回首的计算器代码，也正是知道自己曾经写的代码多么不堪，才知道自己提升代码规范有多么重要。

首先是致力于代码可读性和写明显无bug的代码，然后是将程序可复用性提高。我觉得这篇比较好：【程序员必读】经验：编程的智慧，标题什么的就别吐槽了。同时还有了解了一下RT-Thread的代码规范和uCOS的代码规范。收获三言两语说不明白，也可能因为两个操作系统的代码规范定义并未让我有所收获，就像功夫见人家演练一遍就能学会的，多看几遍也不能，因为你没有对应的内功，就比如之前见过人家的代码风格，但你自己不见得会这样写，因为没有理解掌握只是照着做了可能还自己看得别扭，给自己添堵。

最主要的收获

该时常推敲自己写的代码，每过一段时间就能发现有改进的地方，这也是验证自己能力提升的方式，看编程书籍，写练习代码都是为了这个目的。说起来编程书籍C语言相关的，C缺陷与陷阱，C和指针，C Primer Plus 三本书都不错，我觉得一本比一本好。今天看微信公众号了解到还可以这样：一本编程手册供随时查阅

对于函数分支要写成树状方式，让程序代码不是“面条”，目的是逻辑严密且清晰，不让程序落入未知状态。

对于函数传入参数的验证，不合要求的参数很可能会让程序落入未知状态。就是程序不够健壮。

注释规范

这部分都是因为这篇文章而写的：提取代码中关键信息生成技术文档

估计都会有一个概念，该写注释，为了方便查看，无论是自己还是别人，但是写注释也是有一些讲究的，否则很可能造成只改代码而不改注释，最后效果是七分真三分假，这种情况我觉得注释分散在函数代码块的各处更容易出现。

举一个反面教材吧，我当时写的充电指示部分的程序，因为是通过检测充电芯片的脉冲来判断充电还是充满电，后来又加上了充电时拔线检测，没有充电线检测（ADC检测5V供电）。功能是充电时灯闪烁，充满电若开机状态则指示灯常亮，关机状态则指示灯熄灭，判断拔线后同样。三种情况的判断都是通过检测充电脉冲实现的，而且还不能阻塞其它任务（使用软件定时器实现的），各种分情况处理，那部分代码真是耗费了我不小精力，其中还有些其它原因导致代码写得结构严谨但逻辑不是很清晰。真的不希望再在此处花费太多精力了，也因此写了很详细的注释，涉及到脉冲是怎样的，如何判断的，代码如何实现的。后期代码每次修改一点点，注释也没有改。过了没几天这部分程序需要移植，直接复制粘贴不就可以了吗，还不行，因为软件定时器不让用了，为什么，因为上级的某种经验：使用定时器可能会打断蓝牙的某项功能正常执行，用系统滴答更稳妥些，对此我持怀疑态度。什么芯片有中断功能但不能保存上下文环境导致某项功能异常的，即使有，不是还应该有临界区来避免中断打断吗。本来都通过开源的嵌入式功能模块软件定时器实现功能了。直到后来遇到了个问题，在没找到其它原因的情况下定时器背了锅，（后来找到了其它原因），只能改了，但需要改动的时候才意识到这注释乱而且有真有假，在有注释的情况下看了俩小时才看明白，意识到自己现在的问题，有注释但不是为了让人看明白而准备的。

至此开始寻求规范的注释，公司工程文档里注释写的简单而不够清晰，不是我想要的，本来自己一直摸索着，借不到势，直到看到了这篇文章：提取代码中关键信息生成技术文档。这种风格的注释见得不多，但也有那么几次了，但一直忽略了，不知其所以然而照猫画虎，很容易贻笑大方，更何况当时也没意识到这么写有什么好处，而且还是写英文的，这篇文章让我了解到按照这种规范写，就能生成技术文档的说明，英文并不是那么必要，本来对写英文注释是有抵触的，但可以先把注释格式规范写成习惯了，在随着代码和注释阅读量的上升，一定会写英文注释的。突然又发掘人家的功能模块文档写的真好，看文档就知道实现该功能需要怎么调用了，我想要的说明文档大概就是这样吧。

技术文档生成不止通过注释生成对函数的说明，还包括函数调用关系图，要是没有功能流程图的话，我觉得有个函数调用图对理清程序思路会有帮助。

为什么要分成那么多小函数，每个函数只实现很小的功能呢？因为编代码时可以更专注于功能逻辑一些。而且调试时注销某一部分功能方便。一个函数上百行的话估计编程者自己理清逻辑也不是那么容易。提到这儿我想起来我一位同事写代码的风格了，实现一个功能模块要写三个源文件，只知道一个是底层驱动调用，另外两个不大清楚，写着写着突然感觉就理解了，一个是底层驱动，RGB灯涉及到好多引脚的设置和初始化，如果分离成一个文件，我觉得还是很满意的，第二个文件可能就是中间层文件了，为了实现某部分功能分出去的小功能函数都可以放在这个源文件中，可能会调用其它的硬件驱动，第三个文件就是更接近于功能流程图的处理流程了，只不过还没有进行源文件调用，这第三个文件是为写功能逻辑准备的，而且供实现相应功能而调用。

今后我要努力的方面就是实现三个文件来分层，另外还有就是理清程序的关键点用来输出关键信息，打印次数不多的关键信息该输出出来就别吝啬，否则遇到问题抓瞎一点点儿添加然后编译下载看现象分析再继续添加log输出。这蓝牙芯片调试有些困难，只能通过串口打印，而没有需要用到j-link的这种在线仿真调试。32位的芯片却用着8位单片机用的调试方式。我虽然没用过，但想来即使的8位的STM8和Arduino 调试方式应该也不是那么单一吧。调试方式单一对于新手就太不友好了，自己编的小程序还好，工作中这种调试方式会花费大量时间成本的，导致工作量加大还不出成果，会破坏一整天的心情不说还很危险（如果要求写工作日志的情况下）。

友情提示：一共有三处写入GB2312，只需修改这一处就可以运行通过了，最后什么效果我不敢保证，我第一次都改了，乱码得一塌糊涂。整个过程需要三十多分钟

友情提示，注意核对公众号文章的图片，不要因为没有红框标记就忽略

虽然都是乱码，但技术文档生成的结构算是清晰了。

关于两点儿说明：

如果想要GB2312编码而且还不是乱码，可以先用SourceInsight: 这么好用的代码阅读器你装了吗，然后

再通过doxygon试一次应该就可以了。

使用VScode的Doxygen Documentation Generator插件进行一番设置后，输入/**然后回车，就能生成对应格式的注释，省去了一些重复而繁琐的操作：VScode自动生成Doxygen格式注释

在setting.json中，我的设置如下：

功能流程图和markdown文档说明

关于功能流程图和markdown文档对于短期能力提升效果甚微，但对长远考虑来说，作用巨大。如何知道自己忙忙碌碌且碌碌无为呢：回首过去。有句话叫历史总是重复上演，记录的史书才是一面明镜。对于日常生活来说日记就够了，但是对于程序员（嵌入式软件工程师应该也算是程序员吧）来说，日常的生活更多的是根据需求写代码，改代码。功能流程图和工程的markdown文档更像是程序员的日记，同时也是代码的目录或者是摘要。短期内真的是收效甚微，但花费的时间精力却并不少，但以月以年来计时单位，可以看到自己是在进步还是原地兜圈子。而且总有一条你会认识到代码并不是上来就写的，而是先做规划（在使用C语言这工具之前需要做的事）。图片来自C Primer Plus。功能流程图更像是设计程序的具体实现方式，工程文档更像是阐述实现哪些功能，说明在实现前的准备工作。

功能流程图

功能流程图该怎样写，目前还在摸索阶段，已经写了五六个了（一个工程的），还没借到势，当初问到过一位他是用ProcessOn来画流程图，我当时随手用的WPS的云编辑流程图，刚开始写追求啥专业，不该想法变为行动的初期不应该自我设限（软件使用），而该精心呵护，即使遇到别人的不解与风言风语也不退缩。直到不能满足自己最初的需求而寻找新的方式或者更深入去了解。突然想起来当时mculover666的一篇关于OTA升级的文章流程图不错，STM在线升级OTA