Iris Code Formatter

---
name: iris-code-formatter
description: |
  对InterSystems IRIS/Cache ObjectScript代码进行格式化检查、审查和自动修正。
  当用户需要格式化IRIS代码、检查代码规范合规性、审查代码质量或修正不符合规范的代码时触发此技能。
  支持变量命名、方法命名、锁、事务、陷阱、格式、空行、注释等多个维度的规范检查。
author: 姚鑫
email: 454115408@qq.com
version: 3.1
---

# 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 类注释
```objectscript
/// desc: 类用途描述
/// author：姓名全拼
/// date：YYYY-MM-DD
Class XXX.XXX
```

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

## 使用方法

### 代码审查流程

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

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

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

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

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

```objectscript
; 正确格式 - 括号内运算符两侧加空格，括号与&&之间不加空格
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**: 必须输出完整的修正后代码，不要省略任何部分。将用户提供的完整代码按照规范修正后全部输出。
// 完整修正后的代码（必须包含所有方法，不得省略）

```

## 规范速查表

| 类别 | 规则 | 正确示例 | 错误示例 |
|------|------|----------|----------|
| 变量名 | lowerCamelCase | `startDate` | `startdate` |
| 常量 | 全大写 | `MAXCOUNT` | `MaxCount` |
| 布尔变量 | Flag后缀 | `dispFlag` | `isDisp` |
| 方法名 | UpperCamelCase, 动宾结构 | `GetName()` | `getname()` |
| 布尔方法 | Is开头 | `IsExist() As %Boolean` | `GetExistFlag()` |
| 事务 | 简写小写 | `ts` / `tc` | `TSTART` |
| 锁 | 带+/-和超时 | `l +^XXX:3` | `l ^XXX` |
| 注释符 | #; 或 // | `#; 说明 ` | `; 说明` |
| 空格 | 运算符两侧 | `a = b` | `a=b` |
| 命令 | 除for/while外使用缩写 | `s`, `d`, `q`, `for` | `set`, `do`, `quit`, `f` |
| 系统函数 | 使用缩写 | `$e`, `$p`, `$l`, `$o` | `$extract`, `$piece`, `$length`, `$order` |
| 逻辑运算 | && \|\| | `(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`