IRIS 代码格式化规范

概述

本技能基于作者总结的IRIS代码规范，提供ObjectScript代码的格式化、审查和修正能力。涵盖变量命名、方法命名、锁、事务、陷阱、格式、空行、注释等多个维度，确保代码风格统一、可读性强、维护性高。

> 该技能的作者: 姚鑫

> 作者邮箱: 454115408@qq.com

触发条件

当用户提出以下请求时激活此技能：

"格式化这段IRIS代码"
"检查这段代码是否符合规范"
"审查ObjectScript代码"
"修正代码风格问题"
"按照IRIS规范格式化"
任何涉及IRIS/Cache/ObjectScript代码格式化的需求

核心能力

1. 变量命名规范

1.1 基本原则

禁止使用$、#等特殊符号开始或结束
严禁拼音与英文混合，不允许直接使用中文
参数名、成员变量、局部变量统一使用lowerCamelCase
常量命名全部大写
杜绝不规范缩写，长度为7个以内单词不需要缩写
避免无意义变量（如a, b, c）

1.2 Global命名

临时global：对于临时Global，命名规范以^CacheTemp开头^CacheTemp，不允许有其它的命名。旧命名方式以^TEMP、^Temp、^temp、^TMP、^Tmp、^tmp*、开头的均不合法。
进程global：^||TMP，节点必须携带pid

1.3 特殊变量

布尔变量不要用is开头，使用Flag后缀（如dispFlag）
引用global数据的变量用表ID + Data方式（如bisData）
分割字符串索引统一用i，长度用len
私有对象加m前缀（如mExecute）
禁止使用系统保留字或SQL保留字（如SQLCODE）
调用其他方法返回值用ret，禁止使用err
变量不超过31个字符
百分比变量以%z开头
.inc文件通用变量加前缀标识

2. 方法命名规范

2.1 基本规则

类名、方法名使用UpperCamelCase
返回布尔类型方法以Is开头，加As %Boolean，正向描述（存在返回$$$YES）
推荐使用动宾结构（Get, Set, Query等）
函数/方法名最长不超过30个字符
查询统一用Query，获取数据用Get

2.2 方法组织

一个方法控制在50行以内
方法内传递参数过多时考虑用对象方式重构
禁止在循环里直接写SQL语句（&sql()），SQL语句应当单独建立类来保存
非普通字符串的入参或返回值需要声明类型（数组、对象、流、%Status等）

2.3 错误处理

返回值不能单纯返回负数
字符串形式：负数^错误信息
JSON形式：..RetFail("错误信息")
%Status形式：$$$ERROR($$$GeneralError,"错误信息")

3. 锁规范

禁止直接锁表结构的Global
加解锁必须加+、-严格控制，必须成对出现
加锁必须带+，否则导致解锁进程内所有锁
加锁必须写超时退出（如:3），避免死锁
自定义功能锁格式：^产品组代码(产品线,规范代码:唯一标识)
私有进程全局变量名不能用作锁名
禁止单独使用无参数锁
使用锁时一定要下标节点

4. 事务规范

严格禁止开放性事务（必须有tc或tro）
事务ts、tc、tro位置保持近距离，在一屏幕范围内
严格禁止跨方法提交事务
事务命令简写并且小写（ts、tc、tro）
同一个方法内不应该出现事务嵌套
事务应在保存程序的最外层
单条SQL语句的数据保存不需要事务
ts、tc首尾添加空行或注释

5. 陷阱规范

严格禁止陷阱内部报错导致死进程
Not ProcedureBlock类陷阱名称统一为Err + 方法名
默认类陷阱名称统一为Error
通用陷阱写法：
设置$zt = ""避免死循环
$tl > 0时执行tro避免开放性事务
执行lock避免开放锁

6. 格式规范

6.1 基本格式

方法大括号一律换行显示
运算符（=、+、-、*、/、_、:）左右加空格
逗号后加空格
方法内命令行采用一个Tab缩进（4空格宽度）
禁止命令大小写混用，统一小写
系统命令使用缩写（除for、while外）
系统函数使用缩写（$e, $p, $l, $o等）

6.2 SQL格式

SQL语句一行5个字段
换行后3个Tab缩进
逗号在行末，不带入下行
每行不超过120字符
SQL命令全部统一小写

6.3 字符串格式

单行字符串拼写最多5个字段
禁止用同一变量后加数字累加
获取多返回值用%ArrayOfDataTypes或JSON，不建议字符串拼接

6.4 命令与函数缩写规范

系统命令缩写规则：

for、while 、if 、elseif、else、continue 命令使用全拼（语义明确，表示循环结构）
其他系统命令使用缩写形式

| 全拼 | 缩写 | 说明 |

|------|------|------|

| set | s | 赋值 |

| do | d | 执行 |

| quit | q | 退出/返回 |

| break | b | 跳出循环 |

| kill | k | 删除变量 |

| new | n | 新建变量 |

| write | w | 输出 |

| read | r | 读取 |

| tstart | ts | 事务开始 |

| tcommit | tc | 事务提交 |

| trollback | tro | 事务回滚 |

| lock | l | 加锁 |

| open | o | 打开设备 |

| close | c | 关闭设备 |

| use | u | 使用设备 |

| hang | h | 暂停 |

| job | j | 启动作业 |

| merge | m | 合并 |

系统函数缩写规则：

所有系统函数使用缩写形式

| 全拼 | 缩写 | 说明 |

|------|------|------|

| $extract | $e | 提取子串 |

| $piece | $p | 按分隔符提取 |

| $length | $l | 获取长度 |

| $order | $o | 遍历global |

| $get | $g | 安全获取值 |

| $data | $d | 判断变量是否存在 |

| $find | $f | 查找子串 |

| $ascii | $a | 获取ASCII码 |

| $char | $c | ASCII转字符 |

| $translate | $tr | 字符替换 |

| $justify | $j | 格式化对齐 |

| $zboolean | $zb | 位运算 |

| $zconvert | $zcvt | 编码转换 |

| $zhex | $zh | 十六进制转换 |

| $zdate | $zd | 日期格式化 |

| $ztime | $zt | 时间格式化 |

| $ztimestamp | $zts | 时间戳 |

| $increment | $i | 自增 |

| $random | $r | 随机数 |

| $stack | $st | 堆栈信息 |

6.5 控制结构

尽量使用对仗词（add/remove, get/set等）
禁止{}和.同时出现，推荐使用块级语法
所有if语句都要换行写
if嵌套不宜过多，建议不超过3层
多级if else考虑用$case替换
与或逻辑运算统一使用&&、||
块级语法命令要全拼（for、while而非f、w）
后置表达式要加括号，等号两侧加空格
多条件后置表达式（如 continue: q: 后的条件）：括号内部的条件运算符两侧加空格，括号与&&/||之间不加空格。例如：
正确：q:(inci = "")&&(arcim = "")&&(phcdf = "") - 括号内=两侧有空格，括号与&&之间无空格
错误：q:(inci = "") && (arcim = "") && (phcdf = "") - 括号与&&之间有空格，会导致编译错误
} else { 不换行，写在同一行

7. 空行规范

方法与方法之间空行隔断（1个空行）
空行分割功能相似、逻辑内容相近的代码片段
空行之前添加行注释#; 规则
事务首尾一定要加空行或注释

8. 注释规范

8.1 注释格式

单行注释用#;，句尾注释用//
类、方法头注释用///
各类注释后应跟空格

8.2 注释原则

避免无意义注释，用规范代码命名描述
简明扼要，不要啰嗦
避免错误注释误导

8.3 类注释

/// desc: 类用途描述
/// author：姓名全拼
/// date：YYYY-MM-DD
Class XXX.XXX

8.4 方法注释

/// desc:        方法描述
/// author:      姓名
/// createDate:  YYYY-MM-DD
/// params:      参数说明
/// return:      返回值说明
/// version:     版本
/// modify:      修改记录
/// debug:       调试方法

使用方法

代码审查流程

执行以下步骤审查和修正代码：

读取代码：获取用户提供的ObjectScript代码
逐条检查：按照上述规范逐项检查
标记问题：识别不符合规范的代码位置
提供修正：给出符合规范的修正版本
说明原因：解释每项修正的依据
输出完整代码：必须输出完整的修正后代码，包含所有类定义、方法、注释，不得省略任何部分

关键修正规则（强制执行）

1. 后置表达式处理（关键！）

多条件后置表达式必须严格遵守以下格式：

; 正确格式 - 括号内运算符两侧加空格，括号与&&之间不加空格
continue:(hospId '= "")&&(hospId '= ($p(^CTLOC(locId),"^",22)))
q:(inci = "")&&(arcim = "")&&(phcdf = "")

; 错误格式 - 会导致IRIS编译错误
continue:(hospId '= "") && (hospId '= ($p(^CTLOC(locId),"^",22)))
q:(inci = "") && (arcim = "") && (phcdf = "")

修正逻辑：

识别后置表达式（q: continue: b: 等命令后的条件）
确保每个条件用括号包裹：(条件)
括号内运算符两侧加空格：(a = "") (b <= 0)
括号与&&/||之间绝对不能加空格：)&&( 不是 ) && (
这是IRIS编译器的硬性要求，必须严格遵守

2. 命令缩写规则

for、while、if、elseif、else、continue 使用全拼
其他命令使用缩写：s/d/q/b/k/n/w/r/ts/tc/tro/l/o/u/h/j/m

3. 系统函数缩写

使用缩写形式：$e/$p/$l/$o/$g/$d/$a/$c/$tr/$j/$zb/$zcvt/$zh

输出格式

审查结果应包含：


## 代码审查报告

### 问题汇总
- [严重] 问题1描述（行号）
- [警告] 问题2描述（行号）

### 详细说明

#### 1. 变量命名问题
**位置**：第X行
**问题**：描述
**规范依据**：引用具体规则
**建议修正**：

// 修正后的代码
#### 2. 方法命名问题

...
### 修正后完整代码

**IMPORTANT**: 必须输出完整的修正后代码，不要省略任何部分。将用户提供的完整代码按照规范修正后全部输出。
// 完整修正后的代码（必须包含所有方法，不得省略）

规范速查表

| 类别 | 规则 | 正确示例 | 错误示例 |

|------|------|----------|----------|

| 常量 | 全大写 | MAXCOUNT | MaxCount |

| 注释符 | #; 或 // | #; 说明 | ; 说明 |

| 空格 | 运算符两侧 | a = b | a=b |

| 逻辑运算 | && \|\| | (a)&&(b) | a,b |

| 后置表达式 | 括号内空格，括号外无空格 | q:(a = "")&&(b = "") | q:(a = "") && (b = "") |

参考资源

references/代码规范 - 变量.md
references/代码规范 - 方法.md
references/代码规范 - 格式.md
references/代码规范 - 空行.md
references/代码规范 - 事务.md
references/代码规范 - 锁.md
references/代码规范 - 陷阱.md
references/代码规范 - 注释.md

iris-code-formatter

概述