$ loading_
帮助你撰写不过时的代码注释，聚焦做什么与为什么而非时序背景。
复制安装指令，让 AI 自动完成配置 · 推荐新手
请帮我安装 askskill 上的 "Writing Evergreen Comments" 技能： 1. 下载 https://raw.githubusercontent.com/obra/clank/main/skills/coding/writing-evergreen-comments/SKILL.md 2. 保存为 ~/.claude/skills/writing-evergreen-comments/SKILL.md 3. 装好后重载技能，告诉我可以用了
请为下面这段函数代码编写 evergreen comments。注释只解释“做什么”和“为什么这么做”，不要写临时背景、时间信息、变更历史或诸如“目前”“以后”之类的表达： [粘贴代码]
一版精炼、可长期维护的代码注释，说明函数目的、关键逻辑与设计原因。
请检查下面代码中的现有注释，找出包含时间性、历史性或任务状态的信息，并将其改写为 evergreen comments。保留必要技术意图，删除“临时修复”“等下个版本再改”等表述： [粘贴代码]
标出问题注释并给出改写版本，使注释更稳定、清晰、适合长期维护。
请根据“注释应说明 WHAT 和 WHY，不写 temporal context 或 history”这一原则，为团队写一份简短注释规范。包含推荐做法、禁止写法，以及 3 组好坏示例对比。
一份简洁的团队注释规范，帮助统一编写长期有效的注释。
Comments documenting change history or implementation improvements become stale and confusing. "// Refactored from legacy system" tells nothing about current purpose.
Core principle: Comments explain WHAT code does or WHY it exists, never how it's better than before.
Violating the letter of this rule is violating the spirit of documentation.
Use for:
Use ESPECIALLY when:
Comments describe present state, not past or transitions.
<Bad> ```typescript // Refactored from the old validation system // Now uses Zod instead of manual checking class Validator { validate(data: unknown) { } }// Improved error handling - used to just throw function processRequest() { }
// Recently moved from utils/ to core/ export function helper() { }
</Good> <Bad> ```typescript // Use this pattern instead of the old approach // Copy this when implementing similar features class NewPattern { } </Good> <Bad> ```typescript // Better than the previous implementation // More efficient validation // Enhanced error messages class Validator { } ``` </Bad> <Good> ```typescript // Validates schema in single pass, returns all errors class Validator { } ``` </Good> <Good> ```typescript // ABOUTME: Validates user input against defined schemas // ABOUTME: Provides detailed error messages for debugging <Bad> ```typescript // OLD: Used to validate with regex // NEW: Now uses schema validation for better accuracy function validate(input: string) { // Enhanced validation logic } ``` </Bad> <Good> ```typescript // Validates input against schema, returns structured errors function validate(input: string) { // Business logic here } ``` </Good></Bad>
<Good>
```typescript
// Validates configuration against schema
class Validator {
validate(data: unknown) { }
}
// Returns error details to caller for proper handling
function processRequest() { }
// Shared utility for data transformation
export function helper() { }
Comments document code, not instruct developers.
// TODO: migrate all code to use this function improvedAPI() { }
</Bad>
<Good>
```typescript
// Handles async operations with automatic retry
class RetryableOperation { }
// Validates input before processing
function processInput() { }
Code quality shows in behavior, not comments claiming superiority.
Every file starts with 2-line header explaining purpose.
export class Validator { // ... }
</Good>
**Why ABOUTME:** Greppable pattern for finding file purposes.
```bash
grep -r "ABOUTME:" . --include="*.ts"
| Bad Comment | Why Bad | Good Comment |
|---|---|---|
// Refactored from legacy | Temporal context | // Handles user authentication |
// New error handling | References change | // Returns errors to caller |
// Improved performance | Claims improvement | // Caches results for 5min |
// Use this instead of X | Instructional | // Validates async |
// Wrapper around API | Implementation | // Fetches user data |
// Recently moved here | Temporal context | // Shared validation logic |
Rule: Remove old comments describing old behavior. Don't add new comments about the change.
Critical: Never remove comments unless proven false.
// DO remove if provably wrong
// OLD COMMENT: Returns null on error
function process() {
…
帮助你为变量选择清晰准确、易维护的命名，提升代码可读性。
根据需求先拆解多步骤任务，生成清晰可执行的实施计划