clean-typescript-comments
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseClean Comments
清理注释
C1: No Inappropriate Information
C1：不包含无关信息
Comments shouldn't hold metadata. Use Git for author names, change history,
ticket numbers, and dates. Comments are for technical notes about code only.
注释不应包含元数据。使用Git记录作者姓名、变更历史、工单编号和日期。注释仅用于记录代码相关的技术说明。
C2: Delete Obsolete Comments
C2：删除过时注释
If a comment describes code that no longer exists or works differently,
delete it immediately. Stale comments become "floating islands of
irrelevance and misdirection."
如果注释描述的代码已不存在或运行逻辑已改变，请立即删除它。过时的注释会变成“无关且误导人的孤岛”。
C3: No Redundant Comments
C3：避免冗余注释
ts
// Bad - the code already says this
i += 1; // increment i
user.save(); // save the user
// Good - explains WHY, not WHAT
i += 1; // compensate for zero-indexing in displayts
// 不良示例 - 代码本身已经表达了这个意思
i += 1; // increment i
user.save(); // save the user
// 良好示例 - 解释原因，而非内容
i += 1; // compensate for zero-indexing in displayC4: Write Comments Well
C4：规范编写注释
If a comment is worth writing, write it well:
- Choose words carefully
- Use correct grammar
- Don't ramble or state the obvious
- Be brief
如果值得写注释，就好好写：
- 谨慎选词
- 使用正确语法
- 不要冗长或陈述显而易见的内容
- 简洁明了
C5: Never Commit Commented-Out Code
C5：绝不提交被注释掉的代码
ts
// DELETE THIS - it's an abomination
// function oldCalculateTax(income: number): number {
// return income * 0.15;
// }Who knows how old it is? Who knows if it's meaningful? Delete it.
Git remembers everything.
ts
// DELETE THIS - it's an abomination
// function oldCalculateTax(income: number): number {
// return income * 0.15;
// }谁知道它有多旧？谁知道它是否还有意义？删掉它。Git会记录所有历史。
The Goal
目标
The best comment is the code itself. If you need a comment to explain
what code does, refactor first, comment last.
Good comments usually explain constraints, surprising trade-offs, external contracts, or why an obvious-looking alternative is wrong.
最好的注释就是代码本身。如果你需要注释来解释代码的功能，请先重构代码，再考虑添加注释。
优质注释通常用于解释约束条件、出人意料的权衡、外部契约，或是说明为什么某个看似合理的替代方案不可行。