code-method-normalize

# Java / Kotlin：生成方法的规范化 对 **新生成或改写** 的方法按下列规则整理；**仅改与规范化相关的部分**，不扩大重构范围。 ## 0. 文档风格：JavaDoc vs KDoc（必须分语言） | 语言 | 文档块语法 | 说明 | |------|-------------|------| | **Java** | `/** … */` **JavaDoc** | `{@link …}`、`{@code …}` 等 JavaDoc 内联标签。 | | **Kotlin** | `/** … */` **KDoc** | 内联代码用 **Markdown 反引号** `` `…` ``；类型/符号引用用 **`[…]`**（见下文「类与符号引用」）。**禁止**在 Kotlin 里写 JavaDoc 式的 `{@link …}` / `{@code …}`。 | 同一文件内若同时存在 Java 与 Kotlin，**各自文件内**严格对应上表，不把 JavaDoc 标签抄进 KDoc。 ## 1. 语言差异：入参 `final`（仅 Java） - **Java**：**普通**（非下列例外）方法形参必须加 **`final`**。 - **例外（一律不加 `final`）**： - **`abstract`** 抽象方法（含抽象类或接口中 **无方法体** 的抽象声明）的形参； - **`interface` 中的默认方法**（`default`）的形参； - 标注 **`@Override`** 的实现方法（覆盖父类 / 实现接口）的形参。 - **Kotlin**：**暂不**要求为参数加等价约束（按语言惯例即可）。 ## 2. `@param` / `@return`（JavaDoc 与 KDoc 均适用块标签） - 当方法 **既有非 `void` / 非 `Unit` 的返回类型**，又 **至少有一个入参** 时，必须写 **`@param`**（每个入参一条）与 **`@return`**。 - **`void` / `Unit`**：若无返回语义，见下文第 6 节；若保留且无返回值可描述，可不写 `@return`（以项目既有风格为准时跟随项目）。 ### 2.1 `@param` / `@return` 行里的类型标注（按语言） - **Java（JavaDoc）**：`@param intent {@link Intent}`、`@return {@link Intent}` 等，用 **`{@link 完全限定或简单名}`**（与项目导入/可读性一致即可）。 - **Kotlin（KDoc）**： - **`@param`**：**不要**在参数名后再写 **`[类型]`**；形参类型已在方法签名中，重复标注冗余且易与「正文里对类型的语义说明」混淆。直接写参数语义说明即可。 - **错误**：`@param timestamp [Long] 触发用时间戳，大于 0 时执行一次` - **正确**：`@param timestamp 触发用时间戳，大于 0 时执行一次` - **`@return`**（以及 `<pre>` 等允许符号链接处）：仍可用 **`[类型或符号名]`** 指向返回类型或相关 API，**不用** `{@link …}`。 ## 3. 返回类型为 `Boolean` / `boolean` 时的 `@return` 两种语言都要求 **一句话里写清 true / false 各自含义**（可对举），但 **字面量标记方式不同**： ### 3.1 Java（JavaDoc） ```text @return {@code true} XXXX, {@code false} XXX ``` - **默认**：`XXXX`、`XXX` 为简短中文说明，与业务语义一致。 - **不必强制改成中文**：若已符合上述形式，且两侧说明即可读、能区分语义（例如 `@return {@code true} success, {@code false} fail`、`@return {@code true} yes, {@code false} no` 等常见英文对举），**保留即可**。 ### 3.2 Kotlin（KDoc） ```text @return `true` XXXX, `false` XXX ``` - 使用 **Markdown 行内代码**（反引号）包裹 **`true`** / **`false`** 字面量，**不使用** `{@code true}`。 - 中英文对举规则与 Java 一节相同：新写默认中文；已对举且表意充分时可保留英文。 ## 4. 类与符号引用（补充说明、正文叙述） | 场景 | Java（JavaDoc） | Kotlin（KDoc） | |------|-----------------|----------------| | 指向类、成员、常量等 | **`{@link 包.类#成员}`** 等标准 JavaDoc | **`[ClassName]`** 或 **`[package.ClassName]`** 等 KDoc 符号链接语法 | | 行内代码片段 | **`{@code foo()}`** | **`` `foo()` ``**（反引号） | **注意**：首段摘要中仍遵守第 5 节「禁止直接引用」；`{@link …}` / `` `[Type]` `` / `` `code` `` 等应放在 **`<pre>` 块** 或 **`@return` 行**（Kotlin 的 **`@param` 行不写 `[类型]`**，见第 2.1 节）等允许引用的位置，见下。 ## 5. 方法注释 vs 方法备注（Java / Kotlin 同一套结构） **方法注释**（KDoc/JavaDoc 的 **首段摘要**，通常首行）与 **方法备注**（其后的补充说明）共用下列规则： ### 5.1 首段 / 首行：方法注释（摘要） - **只写方法功能用途**：一句话、**尽可能简短**；可写版本/前提（如「Android 16+：……」）。 - **禁止在首段直接写「代码形态」的引用**，包括但不限于： - **Java**：首段内不出现 **`{@…}`**（含 `{@code …}`、`{@link …}` 等）。 - **Kotlin**：首段内不出现 **反引号代码** `` `…` ``，也不出现 **方括号符号链接** `[…]`（避免首行变成「标识符列表」而非摘要）。 - 首段为 **纯叙述**：说明「是什么 / 干什么」，不夹带可点击或可拷贝的 API 片段。 ### 5.2 方法备注（首段之后的说明块） - 需要补充的场景、风险、滥用说明、API 名、**类/方法引用**、文档链接提示等，**全部放在首段之后**。 - **Java 与 Kotlin 均使用** **`<pre> … </pre>`** 包裹整块备注。 - **`<pre>` 内允许**： - **Java**：`{@code startActivity}`、`{@link Intent}` 等； - **Kotlin**：`` `startActivity` ``、`[Intent]`、`[IntentFilter]` 等 KDoc 写法。 - 与首段分工：**首段 = 是什么/干什么；`<pre>` = 细节、约束、引用、注意事项。** ### 5.3 参考结构 **Java：** ```java /** * Android 16+：关闭系统对 Intent 重定向的启动侧加固 * <pre> * 极少数合法嵌套 {@code startActivity} 场景 * 滥用会增大安全风险，仅当确有需要且已评估后再调用；详见官方「Intent 重定向」说明。 * </pre> * @param intent {@link Intent} * @return {@link Intent} */ @RequiresApi(Build.VERSION_CODES.BAKLAVA) public static Intent removeLaunchSecurityProtection(final Intent intent) { if (intent != null) { intent.removeLaunchSecurityProtection(); } return intent; } ``` **Kotlin（对照 KDoc 写法）：** ```kotlin /** * Android 16+：关闭系统对 Intent 重定向的启动侧加固 * <pre> * 极少数合法嵌套 `startActivity` 场景 * 滥用会增大安全风险，仅当确有需要且已评估后再调用；详见官方「Intent 重定向」说明。 * </pre> * @param intent 待处理的 Intent * @return [Intent] */ @RequiresApi(Build.VERSION_CODES.BAKLAVA) fun removeLaunchSecurityProtection(intent: Intent?): Intent? { intent?.removeLaunchSecurityProtection() return intent } ``` 要点：**首行无 `{@}`（Java）或无 `` `…` `` / `[…]`（Kotlin）**；**`<pre>` 内** 再放具体 API/类型引用；**`@param` / `@return`** 行按第 2、3 节区分 JavaDoc / KDoc（Kotlin 的 **`@param` 不写 `[类型]`**）。 ## 6. 返回值与 `void` / `Unit` - **非必要不写 `void` / `Unit`**：若方法本质是「处理入参并供链式/复用」，优先 **返回有意义的值**；即使「没有额外返回语义」，也可 **返回入参对象**（如上的 `return intent`）或项目约定的空值（如 `null`），便于调用方连续书写。 - **仅在**确实无返回值且不宜伪造返回语义时，再使用 `void` / `Unit`。 ## 7. 异常与崩溃 - **不得**因工具方法未捕获异常而导致主进程 **未处理崩溃**。 - 可能抛出受检/运行时的逻辑：**在方法内 `try/catch`**，记录日志（若项目已有工具类则沿用），**返回安全默认值**（如 `null`、false、原入参、空集合等，与语义一致即可）。 - **避免**将「易在调用方忘记处理」的异常通过 **`throws`** 层层上抛至未捕获崩溃；宁可 **在方法边界消化并返回异常语义下的安全值**。 ## 8. 执行清单（改写方法时自测） - [ ] **Java → JavaDoc、Kotlin → KDoc**，未混用 `{@link}` / `` `code` `` 规则。 - [ ] Java 形参均已 `final`（抽象方法、`interface default`、`@Override` 方法除外不加）。 - [ ] 有非 `void` / 非 `Unit` 返回值且有参：`@param` / `@return` 齐全。 - [ ] **`boolean` / `Boolean`**：`@return` 分支说明齐全——**Java** `{@code true}` / `{@code false}`；**Kotlin** `` `true` `` / `` `false` ``。 - [ ] **首段**无禁止引用（Java 无 `{@}`；Kotlin 无首段 `` `…` `` / `[…]`）；补充说明在 **`<pre>`** 内。 - [ ] **类型引用**：Java 用 `{@link …}`；Kotlin 在 **`@return` 行与 `<pre>` 内** 等可用 `[…]`；**`@param` 行不写 `[类型]`**（见第 2.1 节）。 - [ ] 能用返回入参/有意义值替代的，避免无意义 `void` / 无返回语义的 `Unit`。 - [ ] 危险调用已 try/catch，不依赖未捕获异常传播。