一、命名的重要性
- 命名是编写干净代码的首要技能，通过好的命名，我们可以更深入地理解代码的本质。
二、示例分析
示例1
原始代码：
async function demo(a, b) {
const c = await users(a, b);
return [
avg(c.map(a => a.info[0])),
median(c.map(a => a.info[1]))
];
}
问题：
- 函数名“demo”不明确。
- 参数名“a”、“b”和“c”无意义。
- “a”在map中被重用，导致读者困惑。
- 返回的数组无说明，使用时需注意元素顺序。
- users函数返回结果中的.info字段无说明。
改进后代码：
async function fetchDemographicStatsForFirstNameAndLastName(firstName, lastName) {
const users = await fetchUsersByFirstNameAndLastName(firstName, lastName);
return {
averageAge: avg(users.map(u => u.stats.age)),
medianSalary: median(users.map(u => u.stats.salary))
};
}
改进：
- 函数名明确反映了功能。
- 参数名具有足够的信息量。
- 无需注释，函数名和参数名已足够清晰。
示例2
原始代码（忽略实现细节）：
async function getJobId(machineType, machineRegion, workerDockerImage, workerSetupCmd, jobDescription) {
...
}
问题：
- 函数名隐藏了太多细节，给人一种简单获取的感觉，而实际功能复杂。
改进思路：
无法在不丢失有价值信息的情况下缩短名称，说明函数试图同时执行太多操作，需要分解。
分解后的代码：
async function procureFreeMachine(type, region) {
// ...
}
async function setUpDockerWorker(machineId, dockerImage, setupCmd) {
// ...
}
async function startExecutingJob(workerId, jobDescription) {
// ...
}
三、好名字的特点
- 不误导、不遗漏、不假设。
- 反映所代表的内容或功能。
- 与周围的名字融为一体，组成一个故事。
- 长度遵循范围：名称的寿命越短，范围越小，名称可以越短。
- 坚持在代码库中使用的术语和约定。
四、起名字的技巧
- 在函数/变量上方写下注释，描述其本质。
- 通过凿刻和塑造描述，获得名称。
- 如果名字复杂/令人困惑，说明代码太复杂，需要重构。
- 删除函数/变量上方的注释中已在名称+参数+类型签名中捕获的内容。
五、命名在代码审查中的作用
- 审查代码时，首先关注名称是否清晰。
- 搜索不良名称，可以发现不良代码。
以上是对文档的要点梳理，保留了原文的示例代码，以帮助更好地理解命名的重要性和技巧。
