如何让 AI 更容易读懂你的代码

1、概述复制标题链接

在理解代码结构、类型约束和逻辑关系上，AI 更容易读懂 TypeScript（TS）；但在理解业务意图、上下文背景和自然语言解释上，JSDoc 更有优势。

综合来看，TypeScript 通常被认为是更优的选择，因为它提供了更加严格、紧凑且无歧义的信息。

TypeScript 的优势：精确性与逻辑密度复制标题链接

无歧义性（Unambiguity）复制标题链接

TS 的类型定义是代码的一部分，具有强制性。

function add(a: number, b: number): number

对 AI 来说，这是一个明确的数学约束。而 JSDoc 是注释，有时可能与实际代码不一致，例如代码改了但注释没改，这会导致 AI 产生幻觉或困惑。

结构化能力（Structure）复制标题链接

TS 在处理复杂类型，如泛型、联合类型、交叉类型、映射类型时，语法非常标准化。AI 不需要从自然语言注释中“推测”复杂的对象结构，直接查看 interface 或 type 定义即可。

Token 效率（Token Efficiency）复制标题链接

TS 的语法通常比 JSDoc 更紧凑。JSDoc 需要大量的样板代码，例如：

/**
 * @param ...
 */

这些内容会占用更多的上下文窗口（Token）。TS 能在更少的 Token 内传达同样甚至更复杂的类型信息，让 AI 能读到更多的上下文。

训练数据权重复制标题链接

现代 LLM，例如 GPT-4、Claude 3.5，在大量的 GitHub 代码库上进行训练。近年来，高质量的开源项目大多使用 TS。因此，模型对于 TS 语法的“直觉”往往比对 verbose（啰嗦）的 JSDoc 类型定义更敏锐。

JSDoc 的优势：意图与自然语言复制标题链接

解释“为什么”（Intent）复制标题链接

TS 告诉 AI 参数是 string，但 JSDoc 可以告诉 AI，这个字符串必须是“ISO 8601 格式的日期”或者“用户的 UUID”。

自然语言关联复制标题链接

AI 本质上是语言模型。JSDoc 中的 @description 或纯文本描述能帮助 AI 理解代码背后的业务逻辑（Business Logic）。

// TS：AI 知道只有这三个值
const status: 0 | 1 | 2;

/**
 * 0: Pending
 * 1: Active
 * 2: Banned
 */

通过 JSDoc，AI 可以理解这三个值分别代表什么意义。

AI 视角下的对比示例复制标题链接

假设我们要描述一个用户对象。

JSDoc 方式复制标题链接

/**
 * @typedef {Object} User
 * @property {string} id - The user's unique identifier
 * @property {string} [email] - Optional email address
 * @property {Array<string>} roles - List of roles
 */

/**
 * @param {User} user
 */
function processUser(user) { ... }

AI 读起来需要解析注释块，并将其映射到下方的 JavaScript 代码。如果注释写错了，例如出现拼写错误，AI 可能会误解。

TypeScript 方式复制标题链接

interface User {
  id: string; // The user's unique identifier
  email?: string;
  roles: string[];
}

function processUser(user: User) { ... }

AI 读起来结构一目了然。? 代表可选属性，[] 代表数组，语法是刚性的。

结论与最佳实践复制标题链接

对于 AI 辅助编程，例如 Copilot、Cursor 等：

1. **首选 TypeScript：**用 TS 来定义结构（Structure）和约束（Constraints），让 AI 生成的代码在语法和类型上更加准确。
2. **辅助使用 JSDoc：**用 JSDoc 来补充描述（Description）和上下文（Context）。

AI 最容易读懂的“完美代码”是 TypeScript 加上 JSDoc 描述：

/**
 * 计算用户的年终奖金。
 * 规则：入职满一年才有资格，基于绩效系数计算。
 *
 * @param salary 基础月薪
 * @param performanceScore 绩效分数 (0.0 - 5.0)
 */
function calculateBonus(
  salary: number,
  performanceScore: number
): number {
  // ...
}

总结复制标题链接

如果你想让 AI 写对代码，TypeScript 更好；如果你想让 AI 理解业务，加上 JSDoc 的描述文本是最好的。两者的适当结合是最佳实践。