有些工控设备文档写的真的没法说，我见过甚至不给文档的，找他要问通讯协议，他给你聊天记录一条一条往外崩。你问读哪个寄存器，那就只给你说一个寄存器地址，不说读多长，不说数据什么格式 不说大端小端…整个惜字如金。

我需要在代码里实现这个设备的通信，但我不知道：数据是大端还是小端？浮点数怎么存？读多个寄存器时返回的字节顺序是什么？异常码有哪些？CRC校验用的是哪个多项式？

手册里一个字都没提。

打电话问设备技术支持，对方说"你试一下就知道了"。然后，整的我试了两天。


工控文档的三大流派

干了这么多年，我总结出工控文档有三种典型风格。

第一种："上帝视角派"

文档写得像给自己看的备忘录。只有结论，没有上下文。寄存器表格里写着"地址0x0010，含义：电压，长度2字节。

电压单位是什么？mV还是V？两字节怎么解析，有符号还是无符号，都不说。

你猜。

这种文档的作者大概是觉得"我知道的东西你也应该知道"，所以只写个字母就够了。

第二种："复制粘贴派"

设备A的文档，复制过来改个名字变成设备B的文档。但设备B的协议其实跟A不一样，有些字段已经变了，文档却没更新。

你按照文档写的代码，跑起来全是错的数据。一查发现文档跟实际设备对不上。

更离谱的是，有些文档里的表格甚至还保留着上一个设备的型号名。复制粘贴的时候连替换都没做干净。

第三种："惜字如金派"

这种文档每个字都像是在收费。描述一个寄存器："该寄存器用于存储当前测量值"。

什么测量值？单位是什么？精度几位小数？可读可写还是只读？写入范围是多少？全不说。

你得自己连上设备，一条一条试，反向推导出文档里"忘记"写的东西。


文档烂，后果谁承担？

写文档的人不痛苦，看文档的人痛苦。

下位机出了设备，文档随便写写就交付了。他们对这个设备了如指掌，觉得文档写多写少无所谓。

但上位机工程师呢？你是第一次接触这个设备，你的信息来源就是那几页纸。文档不清楚，你就得：


猜协议格式，猜错了调试半天

打电话问，对方可能也说不清楚

拿串口调试助手一个字节一个字节地抓数据，反向推导协议

写完代码还要反复验证，生怕哪个字段理解错了


一份糊弄的文档，浪费的是下游所有人的时间。

而且这些时间是隐性的。不会有人因为你花两天搞懂了一个没写清楚的协议而感谢你，大家只看结果：要么"设备数据就那几条，读出来了就行。"，要么"这个设备很简单，就采集几个数据，怎么还没通讯上"


一份合格的协议文档应该写什么？

我后来自己写协议文档的时候，总结了一个清单。不算多，但每条都救过命：


1. 基本通信参数
波特率、数据位、停止位、校验位、设备地址范围。别只写"9600,8,N,1"，把每个参数的含义也标注一下。

2. 字节序和数据类型
大端还是小端？整数是几字节？浮点数是IEEE754还是其他格式？BCD码怎么编码？这些是解析数据的前提，不说清楚就是让人猜。

3. 寄存器表
每个寄存器的地址、含义、单位、数据类型、读写权限、取值范围。含义不要只写一个字母，写全称。单位不要省，0.01V和V差一百倍。

4. 完整报文示例
给一两条真实的请求和响应报文，带十六进制和解析结果。这比写十段文字描述都管用。调试的时候直接拿示例对比。

5. 异常处理
设备异常时返回什么？校验失败怎么办？超时多久算通信失败？这些场景不写，出了问题全是黑盒。


以上内容，加起来大概也就三五页纸。但能省下下游工程师几天的时间。


不只是协议文档，所有文档都一样

其实协议文档只是重灾区之一，工控领域其他文档大多也都好不到哪去。

接口文档：后台API的接口文档经常跟实际实现不一致。字段类型对不上，必填项没标，返回格式跟文档说的不一样。联调的时候一边改代码一边骂。

需求文档：甲方写的需求文档往往只有功能描述，没有边界条件和异常场景。"系统需要支持数据导出"，"所有数据单位改成英制"——导出什么格式？数据量多大？是否需要分页？导出失败怎么处理？哪种英制，英寸还是英里，一个都没说。

测试报告模板：有些测试报告的格式要求写得极其模糊，等你做完了报告才发现格式不对，全部返工。


吐槽完了，说说怎么办

光吐槽不解决问题。我给自己定了几条规矩，也分享给你：

第一，自己写文档的时候，按清单来。 你是上游的时候就做好，别让下游的人重复你的痛苦。

第二，拿到烂文档的时候，主动追问，别自己猜。 猜错了浪费时间更多。把你理解的东西整理成一份"补充文档"，发给对方确认。既推进了工作，也留下了记录。

第三，维护一份自己的"协议知识库"。 每次搞懂一个设备的协议，把关键信息记录下来。下次遇到同系列设备就不用从头来了。

第四，如果设备文档实在没法用，自己抓数据逆向一份。 虽然费时间，但有时候就是遇到这种没办法的事，而且这份文档你之后可以反复用，值得投入。


最后

文档这件事，说到底是个职业素养问题。

写文档的人多花一小时，看文档的人能省十小时。 这个比例还真不夸张，经历过的人都懂。

不管是写给同事看的设计文档，还是写给客户看的接口说明，写清楚，写明白，写到位。

这不是在帮别人，是在帮未来的自己。


作者：老码 | 十年程序员，只说自己

你见过最离谱的文档是什么样的？评论区吐槽，咱们比比谁更惨。