133 lines
5.7 KiB
Markdown
133 lines
5.7 KiB
Markdown
---
|
||
name: PHPDoc 规范收紧
|
||
overview: 调整 [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) 第 5 节 PHPDoc 规则：除纯 getter/setter 外，Logic/Service/Model 的 public 方法一律必须写中文 PHPDoc；删除「方法名够清晰可不写」的豁免，并同步 Agent 自查清单。
|
||
todos:
|
||
- id: revise-section-5
|
||
content: 重写 php-clean-code.mdc §5：默认必须、getter/setter 豁免、中文首行、删除旧豁免句
|
||
status: completed
|
||
- id: tighten-must-list
|
||
content: 将原「以下情况必须写」改为「附加要求」，避免被理解为可选项
|
||
status: completed
|
||
- id: update-agent-checklist
|
||
content: 更新 §8 Agent 自查：中文 PHPDoc 全覆盖检查项
|
||
status: completed
|
||
- id: verify-consistency
|
||
content: 通读 Model @property 小节与 §5，确认无冲突表述
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# PHPDoc 规范收紧计划
|
||
|
||
## 背景
|
||
|
||
当前 [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) 存在两条互相削弱的规则：
|
||
|
||
- 第 165 行：`Logic、Service、Model 的 public 方法**建议**写 PHPDoc`
|
||
- 第 167–174 行：仅列举部分场景「**必须**写」
|
||
- 第 203 行：`简单 getter/setter、方法名和类型已足够清晰时，**不强制** PHPDoc`
|
||
|
||
团队诉求：**除纯 getter/setter 外，其余方法都要写 PHPDoc，且以中文说明业务含义**（很多人看不懂英文方法名）。这与已存在的 [Model 类 `@property` 规范](/Users/ray/.cursor/rules/php-clean-code.mdc)（约 123–159 行）方向一致，需统一到同一套原则。
|
||
|
||
## 修改范围
|
||
|
||
**仅改规则文件**（不批量改历史代码）：
|
||
|
||
- [`/Users/ray/.cursor/rules/php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) — §5 PHPDoc 与注释、§8 Agent 自查
|
||
|
||
[`agent-completion-gate.mdc`](/Users/ray/.cursor/rules/agent-completion-gate.mdc) 仍引用「php-code PHPDoc 章节」，无需改路径；完成门禁时 Agent 按更新后的 §5 执行即可。
|
||
|
||
## §5 改写要点
|
||
|
||
### 1. 默认规则：从「建议」改为「必须」
|
||
|
||
将第 165 行改为明确默认值：
|
||
|
||
> **Logic / Service / Model 的 `public` 方法必须写 PHPDoc**（首行中文说明业务动作）；`protected` 方法若承载业务步骤，同样必须。
|
||
|
||
### 2. 唯一豁免：纯 getter / setter
|
||
|
||
用白名单定义豁免，替代原第 203 行「方法名够清晰可不写」：
|
||
|
||
| 可豁免 | 不可豁免 |
|
||
|--------|----------|
|
||
| 无业务分支、无事务、无外部调用的 `getXxx()` / `setXxx()` | `findActiveBySessionId`、`createActiveSession`、`launchWithSession` 等 |
|
||
| 只读/写入单个属性或 DTO 字段 | 名称像 getter 但含查询、状态判断、写入库表 |
|
||
| | `isXxx()` / `hasXxx()` / `ensureXxx()` / `markXxx()` |
|
||
|
||
示例（写入规范正文）：
|
||
|
||
```php
|
||
// 可豁免
|
||
public function getUid(): int { return $this->uid; }
|
||
|
||
// 不可豁免 — 必须中文 PHPDoc
|
||
public static function findActiveBySessionId(string $sessionId): ?self
|
||
```
|
||
|
||
### 3. 方法 PHPDoc 格式要求（中文优先）
|
||
|
||
规定最小合格格式（与现有 Model `@property` 风格一致）：
|
||
|
||
```php
|
||
/**
|
||
* 按对外 session_id 查询未过期且有效的 Launch Session。
|
||
*
|
||
* @throws BusinessException 当 ...
|
||
*/
|
||
public static function findActiveBySessionId(string $sessionId): ?self
|
||
```
|
||
|
||
- **首行必须是中文**，说明「做什么 / 业务结果」，不能只重复英文方法名。
|
||
- 保留现有硬性要求：`array` 结构、`@throws`、状态流转等（作为**附加**要求，不是唯一触发条件）。
|
||
- **禁止废话**：禁止只写 `/** get user */`、`/** @param int $uid */` 而无中文业务说明；禁止与签名完全重复的英文复述。
|
||
|
||
### 4. 删除 / 替换第 203 行
|
||
|
||
删除：
|
||
|
||
> 不要写废话 PHPDoc。简单 getter/setter、方法名和类型已足够清晰时，不强制 PHPDoc。
|
||
|
||
替换为两条并列原则：
|
||
|
||
- **禁止废话**：无信息增量、纯英文复述签名 → 不合格。
|
||
- **除纯 getter/setter 外一律必须**：英文命名不能替代中文 PHPDoc。
|
||
|
||
保留第 205 行「注释解释为什么，不解释做什么」——仅适用于**行内注释**；方法 PHPDoc 首行仍要写「做什么」（中文），复杂处再用行内注释写「为什么」。
|
||
|
||
### 5. 收紧原「以下情况必须写」列表
|
||
|
||
原列表（返回 array、状态流转等）改为 **「以下情况除满足通用要求外，还须额外写明…」**，避免读者误以为「不在列表里就可以不写」。
|
||
|
||
结构示意：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
method[public方法] --> isGetter{纯getter/setter?}
|
||
isGetter -->|是| exempt[可省略PHPDoc]
|
||
isGetter -->|否| required[必须中文PHPDoc首行]
|
||
required --> extra{array或throws等?}
|
||
extra -->|是| addTags[补充结构或throws]
|
||
```
|
||
|
||
## §8 Agent 自查增补
|
||
|
||
在 §8 增加 / 调整检查项（约 245 行后）：
|
||
|
||
- Logic / Service / Model 的 `public` 方法是否均有**中文** PHPDoc（除纯 getter/setter）？
|
||
- 是否存在「只有 `@param`/`@return` 类型、无中文业务说明」的 PHPDoc？
|
||
|
||
可将原「返回 array / 复杂数组 / throws」三条合并表述为「在通用要求之上是否满足附加结构」，避免清单过长。
|
||
|
||
## 不纳入本次范围
|
||
|
||
- **不**批量给存量 PHP 文件补 PHPDoc（体量大，另开重构任务）。
|
||
- **不**强制 Controller / Validate / DTO 全量 PHPDoc（当前 §5 范围是 Logic/Service/Model；若需扩大可后续单独立项）。
|
||
- **不**新增 CI 自动检测脚本（可选后续：`scripts/check-phpdoc.sh`）。
|
||
|
||
## 验收
|
||
|
||
- `php-clean-code.mdc` §5 不再出现「方法名够清晰可不写 PHPDoc」。
|
||
- 新规则与 Model `@property` 小节无矛盾。
|
||
- Agent 自查清单覆盖「中文 PHPDoc + getter/setter 豁免」。
|