065、ABAP文档与注释规范

065、ABAP文档与注释规范那天凌晨两点我被一个诡异的调度问题叫醒。生产环境某个Z程序突然不干活了看代码逻辑完全没毛病数据该取的都取了该更新的也更新了。最后折腾半天发现是上个月有人给这个函数模块加了一个“优化”的注释块里面不小心留了一行带星号的伪代码被ABAP的注释解析器当成了真正的代码段的一部分导致整个方法体被“吞”掉了一截。那行伪代码恰好是*开头在ABAP里就是整行注释但它前面还有半行空格和分号硬生生把注释条件破了防。从那天起我就明白注释这东西写不好比不写更坑人。ABAP的注释家族其实很简单*在行首代表整行注释在行内代表从该位置到行尾的注释。但越是简单越有人玩出花活。比如有人喜欢把放在变量后面做解释结果字符串拼接的时候被当成字符串内容编译不过去还一脸无辜。还有人为了对齐注释在代码结尾敲一长串空格然后写这里干嘛干嘛结果换了一台机器字体变了对齐全乱代码看起来像癫痫发作。真正让我想写这篇的是上周审查一段ABAP代码。那段代码功能没问题但里面几乎没有注释唯一两处注释写成这样* 2019-03-12 修改人张三 原因客户要求 * 2020-07-08 修改人李四 原因优化性能 * 2021-11-30 修改人王五 原因适配新环境三行历史修改记录没有一行说明这段代码到底在干什么。评论区里全是“谁动过这里”“这个逻辑我猜是xxx”“等下这里为什么用LOOP而不是SELECT”大家互相考古像在挖一座没有墓碑的坟。我们不是矫情是ABAP这语言太老了老到连IDE的提示都不如年轻的Python那样友好。一个大型程序动辄上千行没有注释就像进了一间没有灯光的地下室你手里只有一把螺丝刀却要判断哪根电线带电。搞不好你就成了生产事故的背锅侠。那么问题来了怎么注释才算规范别急着背规则先聊聊我实际踩过的坑。第一个坑注释写“为什么”而不是“是什么”。很多新人写注释喜欢对着代码翻译“这个循环用来循环内表”。放屁。我看代码就知道这是个循环你告诉我它循环的意图。是逐条校验是累加汇总还是为了凑某个内表的下标好去索引另一个表我见过最好的注释是“这里不能直接SELECT因为业务上客户可能在同一天提交多笔而接口只允许返回一条所以先按日期排序再取最晚的”。这才是人话而不是编译器在说第二遍。第二个坑注释和代码不同步。改逻辑的时候把代码改了注释忘了。然后半年后你自己回来看着注释提心吊胆这个注释说“这里过滤掉状态为C的记录”可代码明明在过滤状态为D的到底是注释错了还是代码错了你不敢信注释又不敢完全不信只能花半天去翻需求文档结果文档早就过期了。所以我现在给自己立个规矩注释跟着代码走改一行代码如果那行上面三行内有注释必须同时检查注释是否需要改。哪怕只是改个变量名也可能导致注释里的变量名失效。第三个坑滥用*整行注释来“屏蔽”代码。这种操作我见过太多了动不动把一段代码用*全部注释掉然后留在原地。你以为保留了历史其实是给后人埋地雷。首先版本控制工具里什么历史都有不需要你在源码里留坟头。其次被注释掉的代码在阅读时会产生严重干扰——这是不是废弃逻辑是不是可以删掉如果下个版本忘了这个坑把注释打开可能直接覆盖新数据。正确做法是不要的代码就删掉。如果你实在担心那就写一行注释指向版本控制系统的修订号而不是把代码尸体摆在那里。第四个坑文档头信息过于冗长。ABAP程序头部经常有一段注释写程序名、创建人、创建日期、修改记录。这本身没问题但别写成一本书。我见过一个程序头部注释占了80行其中70行是历代修改者表每个人还附带一小段感想。真正有用的信息只有这个程序做什么、入口是什么、依赖什么主数据。至于谁在哪天改了什么交给TADIR或者传输记录吧。第五个坑注释里写脏话或情绪。这不用多解释我们见过把* 这个客户就是个傻逼写进生产代码的。你有情绪写邮件骂别留在程序里。代码会被无数人看到包括客户的技术员以及若干年后的你自己。说完了坑说点具体的写法建议。ABAP的注释位置很讲究。对内联注释一般放在语句后面隔两个空格。不要刚好顶在语句结尾那样分不清是语句的一部分还是注释。比如lv_flag X. 标记为已处理后面不再读这张单据这还算清楚。但如果语句很长注释写到下一行去了那必须用*开一整行并且缩进对齐。我个人的习惯是短注释用行内超过三句话就单独用*多行注释。对于方法或者函数模块的注释我倾向于在定义的上方写一段“为什么”加“使用约束”。比如* 这个函数返回某客户在某时段的分组汇总金额。 * 注意调用前必须确保it_mseg已经按物料号排序否则内表访问会丢数据。 * 不要用这个函数做跨公司汇总因为内部对company_code硬编码了筛选。这就是有效注释。别人调你的函数时第一眼就知道注意事项而不必钻进去逐行分析。ABAP里还有一种特殊的注释用于INITIALIZATION或者TOP-OF-PAGE这种事件块时要小心语法。比如在PBO里写注释没问题。但在某些宏定义里注释会被展开进代码造成预料外的字符。这种极少见但我真的遇到过。所以宏定义内部我尽量不写行内注释只用*整行注释或者干脆不写。再提一嘴ABAP文档生成工具。严格来说ABAP没有像Javadoc那么成熟的文档注释体系但SAP有ABAP Doc!开头能配合ABAP Doc Generator生成API文档。!注释看起来也是注释但它是有结构的。我自己在写需要被外部调用的函数模块时会在函数顶部加一段! p开头的HTML标签描述参数含义。这种注释能被工具捡起来生成漂亮的文档。不过这玩意儿也不是无敌的我提醒一句!注释写坏了不影响编译但会影响文档生成别乱用嵌入标签。比如! p根据内部订单号返回关联的销售订单号如果没有则返回空。/p ! parameter iv_order_id | 内部订单号必填 ! parameter ev_sales_doc | 销售订单号返回时可能为空 ! error 如果内部订单号不存在RAISE EXCEPTION TYPE ZCX_ORDER_NOT_FOUND写这种注释时注意parameter后面的竖线是分隔符空格别省。省了工具识别不了你自己看着也累。对了还有一个细节ABAP代码里字符串前后缀的处理很容易被注释坑到。比如你写了一个语句用CONCATENATE拼接字符串然后你在下一行用注释没问题。但如果你在字符串里用了引号然后行尾写注释编译器可能认为整个字符串还没结束。这是语法解析的锅但写注释的人完全可以避免。我的做法是凡是以字符串结尾的语句行尾不写注释要写就放在上面一行用*整行注释。这样永远不会误解析。还有个跟注释相关的规范叫“注释与代码的密度比”。这玩意儿没有定量标准但我有一个个人的感受一个函数如果少于30行可以不写行内注释但必须有函数头注释。一个函数如果超过150行中途至少要有两处“分节”注释说明这一段在干什么。如果超过300行对不起你该把它拆分函数了。注释再多也救不了“屎山”结构只能给山体喷点除臭剂。回到文章开头的那个事故。后来我在那个函数的前面补了一段注释* 重要提醒本函数禁止在行首使用*做注释因为历史上发生过注释行被误解析为代码块的问题。 * 如需备注统一使用行内双引号且注释内容不得包含分号。虽然这个注释本身也是ABAP注释但谁来谁看到都知道这个文件有特殊禁忌。从那以后再没有人在这个函数里乱用*。最后说点个人的经验。第一注释是写给你自己看的不是写给ABAP编译器看的。你写注释的那一刻假设的读者是“一个月后的你”而不是“刚毕业的大学生”。如果你觉得一个月后的你什么都懂那你就太高估自己了。第二注释要像内裤要有但不必人人都看见更不能穿反。第三最没用的注释是和代码完全重复的废话比如ADD 1 TO lv_cnt. 计数器加1。这种注释建议直接删掉因为它不仅浪费你的字节还污染代码视觉。真正有用的注释永远含有代码里看不出来的信息量为什么这个条件要这样写为什么这个值取的是上限为什么这里不用内连接而用嵌套循环这些才是注释的价值所在。ABAP的世界里注释不是“加分项”而是“保命项”。你不写别人看不懂你自己也看不懂。你瞎写别人会误解然后灾难就会发生。别让一段糟糕的注释变成你深夜守着生产系统盯着屏幕发呆。代码会运行注释会长存。写点人话对得起自己也对得起后来接盘的兄弟。