---
title: "YuiNijika 编码与文档规范"
description: "YuiNijika coding-style and docs-style rules inlined as an online Kasumi skill page."
---


> 编码、写技术文档或提交代码前必须执行 YuiNijika 编码规范与文档规范。

## 适用场景

- 写码或改码：执行下方「编码规范」
- 写技术文档 / README / API / MDX：执行下方「文档规范」

规则全部内联在本页，离线也可用。

## 硬性执行规则

- 不得编造礼貌寒暄、冗长解释或夸张动漫表演。
- 不得猜测未知网络用语或缩写，先查证，无法确认时明确说明。
- 编辑后如代码或说明发生变化，必须运行 typecheck 或 lint 验证；不得把 dev server、构建、安装包下载当普通验证。
- 文件读写只允许文件工具，禁止终端写或改源码：不用 sed、awk、`Get-Content > file`、`Set-Content`、`echo >`、Python 重写文件或单行正则替换。原因是 Windows shell 可能按系统代码页改写，导致 UTF-8 中文乱码。
- 保持工作目录干净：不保留空目录，不生成冗余脚本，不做重复低效的重试。
- 不创造无用的临时文件。测试临时内容放 `.tmp/` 或系统临时目录，用完后删除。

---

# 编码规范

## 优先级

- 项目既有约定优先于本页；本页作为兜底。
- 代码风格跟随所在目录。未约定时按下方规则。

## 文件访问与脚本

- 自动化脚本优先使用 Python，不为小任务写 `.ps1`。
- 仅在真实批量场景使用脚本：数据加工、报告生成、脚手架等。不得用脚本读、改、删源码文件。
- 严格执行文件工具读写，禁止终端写源文件。

## 格式

- 缩进跟随目录约定；无约定时使用 4 空格。禁止 Tab。
- 行尾 LF，禁止 CRLF。
- UTF-8 无 BOM。
- 文件结尾保留一个换行。

## 命名

| 元素 | PHP | C++ | TypeScript | Python | Rust |
| --- | --- | --- | --- | --- | --- |
| 类/接口/结构 | PascalCase | PascalCase | PascalCase | PascalCase | PascalCase |
| 方法/函数 | camelCase | camelCase | camelCase | snake_case | snake_case |
| 变量/属性 | camelCase | snake_case | camelCase | snake_case | snake_case |
| 常量 | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE |
| 文件名 | PascalCase | snake_case | kebab-case | snake_case | snake_case |
| 布尔前缀 | `is`/`has`/`should` | `is_`/`has_`/`should_` | `is`/`has`/`should` | `is_`/`has_`/`should_` | `is_`/`has_`/`should_` |

目录已表达语义时不得重复：`components/Button` 不要写成 `components/ButtonComponent`。

## 类型

- PHP：类型标注齐全，`strict_types=1`。
- C++：参数与返回值使用具体类型，`auto` 仅在能从初始化清晰推断时使用。
- TypeScript：`strict: true`，禁用无说明的 `any`，优先 `interface` 描述对象、`type` 描述联合或交叉。
- Python：公共函数必须有类型标注。
- Rust：优先 `Option<T>` / `Result<T, E>`，不随意 `unwrap()`。

## 代码结构

- 先处理错误或边界，主流程保持浅层。
- 不使用魔法数字；用命名常量或枚举。
- 单一职责：一个函数只做一件事。
- 依赖显式传递，不依赖隐藏全局状态。
- 不混合 UI、业务、数据访问在同一个文件。

## 复杂度守则

### 防过度防御

几乎不会发生的边界或并发问题，不得私自加分叉和防御代码。必须向用户讲清发生概率、触发条件和代价，经用户确认后再加。严禁为了理论上更稳提前膨胀代码。

### 入口单次校验

外部数据只在边界校验一次。内部函数依赖类型系统传递有效数据，禁止层层重复判断同一个字段。每多一层重复判断都是噪声，也会扩大改动面。

### 拒绝提前抽象

单次使用的逻辑就近内联，不提前拆无意义的 helper。只有出现第二个真实使用方，或函数长度确实影响阅读时才考虑抽取。抽象必须有真实复用理由。

### 控制复杂度

非必要不用 `try/catch`。能单函数清晰写清的逻辑不要硬拆成多层。优先让数据流直观、调用链短、失败点明确。

## 注释

注释解释 why，不解释 what。禁止把代码行为逐行翻译成注释。

差：

```ts
// Return the result
return result;
```

好：

```ts
// React batches state updates so two calls still render once
```

仅对复杂逻辑、公共 API 契约、特殊异常、不明显结构写文档注释。

## 语言重点

- PHP：新文件 `declare(strict_types=1)`，纯 PHP 省略 `?>`，Controller 保持薄层。
- C++：`#pragma once`，header 不写 `using namespace std;`，优先智能指针和 `enum class`。
- TypeScript：3 个以上参数用对象参数，异步只写 `Promise<T>` 配 `async/await`。
- Python：PEP 8，公共函数标注类型，优先 f-string 和 pathlib。
- Rust：`rustfmt` / `clippy` 干净，优先借用避免克隆。

---

# 文档规范

## 页面结构

除用户另有指定外，技术文档按此骨架：

```md
# 页面标题

> 一句话说明本页覆盖什么、解决什么问题。

## 模块边界 / 适合谁阅读 / 入口

## 核心内容

## 代码示例

## 常见问题 / 常见风险 / 排查路径
```

必须包含：

1. 具体能力标题，不使用营销标语
2. 一句话范围说明
3. 先写边界：本页是什么、不是什么
4. 真实入口：文件、函数、Hook、配置键、加载顺序
5. 表格表示层级、字段、文件、优先级
6. 可运行示例：真实命名、真实调用形状、真实守卫
7. 反例：说明不该怎么做
8. 复杂主题必须有排查路径或症状表

## 内容纪律

- 文档必须回答：入口在哪、加载顺序、如何调用、读取、扩展、什么不该碰、失败如何排查。
- API、路径、Hook、配置键必须基于真实代码或已验证事实，禁止虚构。
- 不确定时给出验证方法，不编造细节。
- 默认简体中文，语气直接冷静，短段落。
- 不写“非常强大、灵活、易扩展”这种无机制的句子。
- 不把聊天式片段写进技术文档。

## 示例要求

- 代码示例必须符合本页编码规范。
- 涉及权限、付款、下载、库存等敏感场景必须包含守卫和幂等说明。
- 展示反例时注明错误点。

## 文档检查清单

收尾前逐条检查：

1. 开发者能否在 30 秒内找到入口文件？
2. 加载、读取、写入、扩展路径是否明确？
3. 结构重要的地方是否使用表格？
4. 示例是否真实、可直接复制、符合编码规范？
5. 是否明确列出不该做的路径？
6. 是否有失败排查路径？
7. 是否凭空发明了名称或路径？

若有任意一项不满足，先重写再交付。