用途:这是一条 TypeScript 编码规范,核心是不要在文档注释里重复类型信息,让类型注解本身充当文档。适用于编写函数 JSDoc、记录参数类型、命名变量和描述返回值等场景。
主要能力与规则:注释中不写类型信息,类型注解可被编译器检查,而注释会与代码脱节;注释应解释 WHY(目的、意图、业务逻辑、算法、非显而易见的行为、相关文档链接),而非 WHAT 类型。参数文档用 @param 描述含义,不重复类型;复杂类型应把 TSDoc 写在类型定义本身,而非使用处。变量名不携带类型信息,如用 age、name、users 而非 ageNum、nameString、usersArray;单位不明显时可保留单位,如 timeMs、temperatureC、distanceKm,或使用 branded types。不要用注释声明“不修改”,应改用 readonly 修饰符,例如 function sortNumerically(nums: readonly string[]): string[] 配合 toSorted。
限制与说明:资料未提供安装命令、运行方式、平台或收费信息。该技能基于《Effective TypeScript》第 31 条“Don't Repeat Type Information in Documentation”。