第六章 写出言简意赅的注释

如果你要写注释，最好把它写得精确——越明确和细致越好。另外，由于注释在屏幕上也要占很多的地方,并且需要花更多的时间来读，因此，注释也需要很紧凑。

关键思想

注释应当有很高的信息/空间率。

让注释保持紧凑

下面的例子是一个 C++ 类型定义的注释

// The int is the CatagoryType.
// Hte first float in the inner pair is the 'score'
// the second is the 'weight'
type of hash_map<int, pair<float, float>> ScoreMap;

可是为什么解释这个例子要用三行呢？用一行不就可以了吗？

// CategoryType -> (score, weight)
type of hash_map<int, pair<float, float>> ScoreMap;

避免使用不明确的代词

润色粗糙的句子

精确地描述函数的行为

用输入、输出例子来说明特别的情况

对于注释来讲，一个精心挑选的输入/输出例子比千言万语还有效。

例如，下面是一个用来移除部分字符串的通用函数:

// Remote the suffix / prefix of "chars" from the input src
String Strip(String src, String chars) { ... }

这条注释不是很精确,因为它不能回答下列问题：

• chars 是整个要移除的子串，还是一组无序的字母?
• 如果在 src 的结尾有多个 chars 会怎样?

然而一个精心挑选的例子就可以回答这些问题：

// Example: Strip("/abba/a/ba", "ba") return "/a/"
String Strip(String src, String chars) { ... }

这个例子展示了Strip()的整个动能。请注意,如果一个更简单的示例不能回答这些问题的话,它就不会那么有用

// Example: Strip("ab", "a") return "b"
String Strip(String src, String chars) { ... }

声明代码的意图

// 计算数组元素的平均值（忽略非数字元素）
function calculateAverage(values: any[]): number {
    // ... existing code ...
}

具名函数参数的注释

// 定义一个用户对象的参数
interface UserParams {
    /** 用户ID（必须为UUID格式）*/
    id: string;
    /** 用户年龄（0-150有效范围）*/
    age: number;
    /** 是否验证邮箱（默认false）*/
    verified?: boolean;
}

function createUser({ id, age, verified = false }: UserParams) {
    // ... existing code ...
}

采用信息量高的词

// 用专业术语替代普通词汇
function sanitizeInput(input: string): string {  // 原方法名 cleanInput
    // ... existing code ...
}

总结

本章是关于如果把更多的信息装入更小的空间里。下面是一些具体的提示：

• 当像 it 和 this 这样的代词可能指代很多个事物时，避免使用它们。
• 尽量精确的描述函数的行为。
• 在注释中用精心挑选的输入/输出例子进行说明
• 声明代码的高层次意图，而非明显的细节
• 用嵌入的注释来解释难以理解的函数参数
• 用含义丰富的词来时注释简洁