当前位置：首页 > ops >正文

代码可读性的详细入门

ops 2025/9/6 16:03:44

🏠个人主页：尘觉主页

文章目录

前言
一、可读性的重要性
二、用名字表达代码含义
三、避免名字歧义
四、良好的代码风格
五、注释的价值
六、如何编写注释
七、提高控制流的可读性
八、拆分长表达式
九、变量与可读性
十、抽取函数
十一、一次只做一件事
十二、用自然语言表述代码
十三、减少代码量
- 😄总结

前言

在软件开发中，
程序员大部分时间并不是在写代码，而是在读代码。我们要阅读自己的代码，也要阅读他人的代码。代码的可读性不仅影响开发效率，还会直接影响项目的长期维护成本。可读性良好的代码能够降低沟通成本，减少理解错误，并且让重构与扩展更加容易。相反，晦涩难懂的代码不仅容易埋下 bug，还会让团队成员不愿意修改它，从而影响整个系统的健康演进。

本篇总结了如何提升代码可读性的实用方法，涵盖命名、注释、风格、控制流设计、变量管理、函数抽取等方面，为开发者提供系统化的参考。

一、可读性的重要性

编程有很大一部分时间是在阅读代码，可读性良好的代码能显著提升效率和质量。只有在极少数性能关键场景下才可暂时牺牲可读性，其余情况下，可读性应当被放在首位。

二、用名字表达代码含义

选用语义化单词：
- send → deliver、dispatch、announce、distribute、route
- find → search、extract、locate、recover
- start → launch、create、begin、open
- make → create、set up、build、generate、compose、add、new
循环迭代器避免 i, j, k，可改为 userIndex、memberIndex。
名字长度与作用域成正比：作用域大 → 名字长，作用域小 → 名字短。

三、避免名字歧义

先思考别人是否会误解这个名字。
布尔命名加前缀：is、can、should、has。
数量范围：min、max；空间范围：first、last；排除范围：begin、end。

四、良好的代码风格

使用空行和缩进组织逻辑。
对齐注释，保持整齐：

int a = 1;   // 注释
int b = 11;  // 注释
int c = 111; // 注释

变量定义顺序应与业务对象顺序一致。

五、注释的价值

不要为显而易见的代码写注释，如 getter/setter。
注释不是名字的替代品，应优先写好变量名。
注释可用于：
- 记录设计思路；
- 提醒特殊情况；
- 标记未完成工作：

标记	用法
TODO	待做
FIXME	待修复
HACK	临时粗糙方案
XXX	危险，需特别注意

六、如何编写注释

简洁清晰：

// Student's name -> Student's score
Map<String, Integer> scoreMap = new HashMap<>();

用示例说明：

// Example: add(1, 2) returns 3
int add(int x, int y) {return x + y;
}

使用专业名词缩短解释。

七、提高控制流的可读性

条件表达式：变量在左，常数在右。
三目运算符仅限逻辑简单的情况。
避免使用 goto。
在循环中使用 return 减少嵌套。

八、拆分长表达式

使用解释性变量：

username = line.split(':')[0].strip()
if username == "root":...

运用逻辑定律简化表达式：

if (!(a || b)) { ... }

九、变量与可读性

减少控制流变量：用 break/return 替代布尔标记。
减小作用域：变量应尽量靠近使用点。
避免全局变量：JavaScript 中应始终用 var/let/const 声明变量。

优化示例

原始代码：

var setFirstEmptyInput = function(new_value) {var found = false;var i = 1;var elem = document.getElementById('input' + i);while (elem != null) {if (elem.value === '') {found = true;break;}i++;elem = document.getElementById('input' + i);}if (found) elem.value = new_value;return elem;
}

优化后：

var setFirstEmptyInput = function(new_value) {for (var i = 1; true; i++) {var elem = document.getElementById('input' + i);if (elem === null) return null;if (elem.value === '') {elem.value = new_value;return elem;}}
};