110 lines
4.7 KiB
Markdown
110 lines
4.7 KiB
Markdown
---
|
||
name: code-hygiene
|
||
description: >-
|
||
Inspect and clean up code in the Seek-Battle-Evacuate (SBE) project according to AGENTS.md
|
||
null-checking rules, error handling specifications, and anti-defensive programming guidelines.
|
||
Use this skill whenever the user asks to format code per AGENTS.md, clean up redundant null checks,
|
||
remove over-defensive fallbacks, or review code hygiene.
|
||
---
|
||
|
||
# SBE Code Hygiene & Defensive Cleanup
|
||
|
||
本技能用于规范 SBE 项目中的 C# 代码质量，消除过度防御（Over-Defensive Programming）、冗余判空与静默吞错，严格对齐 `AGENTS.md` 规范与敏捷“Fail Fast”（快速失败）原则。
|
||
|
||
---
|
||
|
||
## 一、三项核心红线（AGENTS.md 必须遵守）
|
||
|
||
1. **声明处已初始化的变量，之后绝对不判空**
|
||
- 坏：字段或局部变量已有 `= new List<T>()` / `= new Dictionary<...>()`，后续还写 `if (_list != null)`。
|
||
- 好：直接使用 `_list.Add(...)`、`_list.Clear()`。
|
||
|
||
2. **严禁静态兜底与静默回退（Fail Fast 原则）**
|
||
- 坏：找不到数据、缺少配置或解析异常时，返回硬编码默认值（如 `global != null ? global.Time : 250` 或 `if (cfg == null) return 10;`）。
|
||
- 好：异常路径直接 `Log.Error(...)` 报错并中断执行（`return` / 抛异常），绝不用伪造数据让程序带病运行。
|
||
|
||
3. **UI 序列化字段与 View 自动绑定字段不做判空**
|
||
- 坏：`if (View != null && View.sortButton != null)`、`[SerializeField] private Button _btn; ... if (_btn != null)`。
|
||
- 好：默认信任 Inspector 和 `UIAssetsTools` 自动绑定。若没绑定本应报错暴露，不加空防御掩盖。
|
||
|
||
---
|
||
|
||
## 二、六项常见“没必要”的过度防御与坏味道
|
||
|
||
在 Unity / UGF / C# 实际开发中，以下写法通常是冗余、降低代码可读性且增加维护负担的：
|
||
|
||
### 1. 集合遍历前的非空/长度双重检查
|
||
- **没必要**：
|
||
```csharp
|
||
if (list != null && list.Count > 0)
|
||
{
|
||
foreach (var item in list) { ... }
|
||
}
|
||
```
|
||
- **原则**：若列表规范为非空对象（即使为空也是包含 0 个元素的空列表），`foreach` 会自动直接跳过，根本无需任何 `if` 守卫：
|
||
```csharp
|
||
foreach (var item in list) { ... }
|
||
```
|
||
|
||
### 2. LINQ 与内建构造返回值的非空检查
|
||
- **没必要**：
|
||
```csharp
|
||
var results = items.Where(x => x.Active).ToList();
|
||
if (results != null) { ... } // ToList() 永远返回新 List 实例，永不为 null
|
||
```
|
||
- **原则**：直接使用 LINQ 投影/转换结果。
|
||
|
||
### 3. 内部私有辅助方法的层层重复防御
|
||
- **没必要**：公有入口方法已经做了入参断言/校验，拆分出来的内部私有方法 `private void ApplyCore(Item item)` 每一层都再写一遍 `if (item == null) return;`。
|
||
- **原则**：私有方法属于内部信任边界，保持干净直白，将校验集中在业务入口。
|
||
|
||
### 4. 字典的双重查找（Double Lookup）
|
||
- **没必要**：
|
||
```csharp
|
||
if (_dict.ContainsKey(key))
|
||
{
|
||
var val = _dict[key];
|
||
...
|
||
}
|
||
```
|
||
- **原则**：统一使用 `TryGetValue`，减少一次哈希哈希计算与冗余判断：
|
||
```csharp
|
||
if (_dict.TryGetValue(key, out var val))
|
||
{
|
||
...
|
||
}
|
||
```
|
||
|
||
### 5. 静默吞异常的空 Try-Catch
|
||
- **没必要**：
|
||
```csharp
|
||
try { DoSomething(); }
|
||
catch (Exception) { /* 留空，或者只 Log.Warning 假装没事 */ }
|
||
```
|
||
- **原则**：非预期异常必须 `Log.Error(...)` 暴露上下文并附带具体错误信息，绝不能掩盖致命逻辑错误或数据存盘缺失。
|
||
|
||
### 6. MonoBehaviour/实例方法内的自我判空
|
||
- **没必要**：在普通实例方法内部写 `if (this == null)`，或对由 Unity 生命周期保证的对象进行反复探测。
|
||
- **原则**：信任正常的组件调用生命周期。
|
||
|
||
---
|
||
|
||
## 三、代码排查与清理步骤（Runbook）
|
||
|
||
当用户发出整理请求时，按以下流程执行：
|
||
|
||
1. **识别范围**：
|
||
- 检查 `git status` 涉及修改的文件，或针对用户指定的代码文件。
|
||
2. **逐项审查**：
|
||
- [ ] 检查是否有 `[SerializeField]`、`View.xxx` 的判空，有则移除。
|
||
- [ ] 检查声明处赋值（如 `= new ...`）字段的二次判空，有则移除。
|
||
- [ ] 检查是否有配置读取、存档读取的三元默认值回退（`?:` 魔法数字），改为 `Log.Error` 并中断。
|
||
- [ ] 检查 `foreach` 外层是否有冗余的 `if (list != null && list.Count > 0)` 嵌套，若列表非空则拍平。
|
||
- [ ] 检查是否有空 `catch` 吞错。
|
||
3. **推演逻辑边界（静态检查）**：
|
||
- 确认移除防御后不会导致不可预知的崩溃；
|
||
- 确认异常路径是否确实按规范输出了 `Log.Error`。
|
||
4. **汇报改动**：
|
||
- 列出修改的文件路径；
|
||
- 简要说明移除了哪些冗余防御或规范了哪些异常断言。
|