究竟什么才是优秀的代码上周Code Review组里一个新同事提交了一段Python脚本功能是实现某个文件的解析和重写。代码逻辑完全正确跑起来没有任何bug但我在屏幕前足足坐了十几分钟才看懂他写了什么。全部变量名是a、b、c函数名是fun1、fun2中间还有一段八层嵌套的列表推导式注释只有一行“处理数据”。我说你这段代码能跑但很难维护。他反问了一句“能跑不就行了吗反正功能是对的。”这句话让我想了很久。究竟什么才是优秀的代码这是一个看似简单、其实特别难回答的问题。在技术社区混了十几年我见过太多代码——有的运行效率极高但没人敢碰有的设计精妙但接手的人想骂娘有的麻雀虽小五脏俱全有的几百个类相互调用最后谁都不敢改。我自己的答案也在不断变化刚工作那两年觉得跑得快的代码是好代码后来觉得可读性最重要再后来带团队做项目又发现可维护性、可测试性、可扩展性这些维度的优先级往往比“性能极致”更高。这篇文章我想从自己的实际项目经验出发聊一聊我对“优秀代码”这件事的真实理解。不搞理论说教不谈哲学就拿真实场景中的代码做例子——包括之前项目里写过的强化学习训练代码、量化策略脚本、OpenCV标定工具、甚至C的我的世界风格小游戏代码我会一五一十讲清楚什么情况下你觉得“这代码写得真烂”什么情况下你会由衷感叹“这代码写得真好”。不管你是刚入行的新手还是带了几年团队的技术负责人应该都能从中找到对自己有用的东西。1. 破题优秀代码的标准从来不是单一维度1.1 从“能跑”到“好维护”之间隔着什么先聊一个最常见也最容易被误解的点“代码能跑”和“代码优秀”之间到底隔了多少东西我见过太多处于“能跑”状态的代码。说句公道话能跑本身已经是一种能力了调试过几千行代码的人都明白能跑意味着逻辑基本自洽边界条件大体处理完了。但“能跑”只是底线不是目标。举个例子之前我们团队接过一个遗留系统里面有一段C语言的文件读写操作。功能确实完全正常读取配置文件、解析字段、写入日志每步都不会崩溃。但这段代码有个特点函数名是process_data参数是char *p1, int n1, char *p2, int n2没有任何注释。我接手的时候花了整整一个下午从上层调用一点点往下追才搞明白p1是输入文件路径n1是缓冲区大小p2是输出文件路径n2是输出缓冲区大小。其中有几个边界条件比如文件不存在时函数会自动创建一个空文件——这个行为根本没有写在任何文档里是我用测试用例试出来的。“能跑”的代码让机器满意“优秀”的代码让人满意。机器只需要正确地执行指令序列但人的大脑处理信息的能力是有限的。一段代码写完之后它会被更多人读、改、维护、扩展。人在这个过程里需要付出的理解成本才是评价代码质量时最核心的变量。我自己实测下来的感受是代码阅读时间与修改成本呈指数关系。一个变量名表意清晰的函数可能30秒就能理解意图一个变量名全是a、b、c的函数想搞清楚它在干什么往往需要从调用处一路追查而等项目轮转到第三个人手里时花的时间就会从30分钟变成3个小时。这个成本增量在个人项目里你感受不到一旦进入团队协作它会无限放大。1.2 需求变了代码也会从优秀变成平庸还有一点很重要“优秀”是相对的不是绝对的。一段代码在某一个时间点很优秀但需求一变它可能立刻变成维护的噩梦。我记得有一次写一个量化交易策略的Python脚本当时用的一个技术指标计算函数把所有中间结果都缓存到了实例变量里为了性能做了大量原地操作。当时这段代码跑起来飞快对历史行情回测1000次只需要几秒钟我觉得自己写得简直完美。但后来策略要扩展需要把指标参数暴露给外部配置并支持多种参数组合的批量测试。我一回头发现那个极度优化过的计算函数被十几个状态变量搅在一起根本无法安全地并发调用——批量测试一旦并行执行各个实例之间就互相污染数据。我不得不花了一整个周末把它重构成纯函数形式把缓存全部去掉换来的结果是性能从几秒降到了几十秒但代码逻辑变得异常清晰所有依赖都显式传递测试也好写了。这个经历给我的教训是在写代码的时候永远要问一句“这个代码以后会被怎么改”。如果答案里有“可能会换参数”“可能会并行调用”“可能会增加新的分支”那么当时为了省几行代码做的隐式状态和全局耦合迟早会变成你需要加倍偿还的技术债。1.3 优秀代码的第一性原理综合这些年我踩过、填过的坑我想把“优秀代码”的讨论收敛到第一性原理上代码是写给人看的只是顺便被机器执行。这句话不是我发明的但在实际写代码的过程中它逐渐成了我判断代码好坏的第一准则。从这个准则出发优秀代码需要回答的不是“能不能跑”而是“读代码的人能不能在最短时间内理解它”。它需要回答的不是“性能是否极致”而是“在可接受的性能范围内代码逻辑是否清晰且易于演化”。算法竞赛里的代码和工业项目的代码、个人玩具脚本和团队长期维护的系统代码对“优秀”的定义完全不同。所以你如果问我“究竟什么才是优秀的代码”我的答案是在可接受的运行效率内把逻辑表达得足够清晰、足够容易修改、足够方便测试、足够让团队里任何一个人都能快速上手的代码。接下来的几个章节我会结合不同场景把这句话拆开揉碎了讲。2. 场景拆解不同领域对“优秀代码”的衡量标准差异很大一个码农日常接触的代码远不止一种类型。我在一个中型项目里同时维护过Python深度强化学习代码、C图像处理工具、前端JavaScript脚本和Shell部署脚本感受非常深刻——这些代码“优秀”的标准完全不同用一个标准衡量所有代码本身就是外行行为。2.1 算法研究类代码正确性优先但可复现性越来越重要先拿热搜词里出现频率最高的两个东西说事TD3代码和快速排序代码。TD3Twin Delayed DDPG是深度强化学习里一个经典的连续控制算法。我看过很多人Pytorch实现的TD3包括GitHub上几个star数很高的开源实现和初学者自己照着论文写的复现。这类代码有一个显著特点算法逻辑本身是固定的难点在于一堆超参数学习率、噪声标准差、延迟更新的步数、目标网络平滑系数和训练流程经验回放、软更新、策略噪声对最终效果影响极大。一个优秀的TD3实现在我眼里应该具备两个特征。第一论文里的关键公式与代码有清晰对应关系比如目标Q值计算的时候那个reward gamma * min(q1_target, q2_target)一定要能让读者一眼对应到论文里的公式第二所有超参数必须集中管理最好放在一个config对象里或者文件开头方便做消融实验时批量调参。第三实验的可复现性极其重要——固定随机种子、保存模型权重、记录训练日志这些在算法研究代码里甚至比算法本身更重要。快速排序的情况也很有意思。教科书版本的快速排序通常长这样def quicksort(arr): if len(arr) 1: return arr pivot arr[len(arr) // 2] left [x for x in arr if x pivot] middle [x for x in arr if x pivot] right [x for x in arr if x pivot] return quicksort(left) middle quicksort(right)这段代码清晰干净任何人都能看懂但它的空间复杂度是O(n)而且对已排序数组性能很差。我在项目里实际用的是原地排序版本但我会把那个版本封装成一个类对外只暴露sort(arr)接口内部实现无论多复杂调用者都不需要关心。可读性和性能并不冲突关键看你把复杂度放在哪一层。对外接口简单内部实现可以复杂但内部复杂的前提是命名清晰、注释到位、结构合理。相反如果一个函数既要求极致的性能内部交叉耦合又乱成一团那才是真正的灾难。2.2 业务系统类代码可维护性的优先级压倒一切再来说业务系统代码比如量化交易策略、网站后台服务一类。这种代码生命周期长需求变化频繁可能一个函数从“返回价格列表”变成“返回去重后的、按时间排序的、过滤掉停牌股票的价格列表”变到最后最初的作者自己都认不出来。我在写量化策略脚本的时候感受最深。策略代码本质上是一个状态机接收行情信号、根据信号计算持仓、生成订单、处理成交回报。任何一个环节出错轻则回测结果失真重则实盘资金损失。所以这类代码的“优秀”标准非常明确逻辑链路必须清晰到可以被逐行审查关键计算过程必须有日志输出盈亏统计必须可以复现。我自己写量化代码有个习惯永远把策略逻辑和数据处理完全分离。数据清洗单独一个模块指标计算单独一个模块信号生成单独一个模块下单执行单独一个模块。这样每部分都可以独立测试出了问题也可以快速定位。很多新手喜欢把各种逻辑写在一个函数里从读取数据到计算指标再到下单信号一气呵成回测的时候方便但一旦实盘环境出了诡异问题找bug的难度会指数级上升。2.3 图像与底层开发类代码性能和可读性的平衡OpenCV棋盘格标定和C代码话题我也来聊几句。图像处理类代码往往是性能敏感型的对每一帧图像、每个像素的处理都追求极致效率。但是基于OpenCV的棋盘格标定代码有特殊性——标定不是实时任务它运行一次输出一组相机内外参数耗时几秒到几十秒都可以接受。所以对于这类工具型代码我反而更看重可读性。你拿C写一个棋盘格标定程序如果在cv::findChessboardCorners前没有注释说明输入图像需要什么预处理在标定矩阵计算前没有说明坐标系定义那么三个月后你自己翻这段代码都头疼。性能在这里不是瓶颈理解成本才是。我有一个习惯只要是图像处理类的工具代码必须在文件头部写明“输入是什么、输出是什么、坐标系怎么定义、依赖哪个版本的OpenCV”。这几个信息看似基础但在项目交接时价值极大能省下对方好几天的摸索时间。2.4 个人项目与玩具代码能解决问题就是好代码当然也不是所有代码都要按工业标准来要求。我回看自己写的个人项目代码比如一个用来生成爱心图案的Python脚本、一个简单的罗盘时钟JavaScript页面、一个用C语言写的娱乐性质小游戏这些代码如果按团队项目的标准评判简直千疮百孔没有单元测试、没有错误处理、甚至有些变量名想都不想直接乱取。但我觉得它们是好代码。为什么因为它们的目的是自娱自乐、验证某个想法、或者快速交付一个可用的玩具。在这种场景下代码只要能解决问题、能让我第二天还能看懂就够了。我始终认为一个连个人玩具项目都要上全套设计模式的人要么是在浪费时间要么根本不懂什么场景该用什么复杂度。3. 优秀代码的六大核心特征拆解3.1 可读性命名不是小事是全局性的大事如果说优秀代码只能有一个特征我选可读性。而可读性里最直观的体现就是命名。我见过一段C语言代码变量名是int n, m, k函数名是void solve()循环里全是for(i0; in; i)。当你追代码的时候你必须反复跳回定义处确认每个变量含义这种精神力消耗特别大。好的命名到底是什么标准我的衡量方式是读代码的人能不能在不看注释的情况下凭借变量名和函数名推断出80%以上的逻辑意图。举个例子// 差劲的命名 int f(int x) { int y x * 10; if (y 100) return 100; return y; }// 好的命名 int clamp_to_max_price(int original_price) { int price_with_markup original_price * MARKUP_RATE; return min(price_with_markup, MAX_DISPLAY_PRICE); }第二个版本没有任何注释但你看一眼就知道它在做什么。这就是命名的力量。我自己的命名经验可以总结成三句话变量名要体现业务含义而非类型函数名要用动词开头描述行为布尔变量名要能回答是或否的问题。遵循这三条代码的可读性就能上一个台阶。3.2 可测试性你写的代码能不能被“拷问”3.3 健壮性错误处理不是“加try-catch”那么简单3.4 性能与复杂度的合理取舍3.5 可扩展性不要为明天的功能过度设计3.6 团队协作友好度代码是沟通的媒介4. 实操方法论从“能跑”到“优秀”的四步进阶法4.1 写之前先想清楚接口和边界条件4.2 写的过程中保持小步提交与持续自查4.3 写完后代码评审优秀代码必经的历练4.4 重构的时机判断与具体操作步骤5. 常见问题与排查技巧实录5.1 命名混乱的老代码如何安全接手5.2 代码“看起来都对”但运行时就是不对5.3 性能问题定位的三个常用手段5.4 团队代码风格不统一的解决思路6. 我对“优秀代码”的最终判断清单6.1 一张可直接使用的代码质量检查表6.2 个人实际使用中的体会与心得6.3 一个小技巧用“半年后的自己”作为评审标准最后再多说一句最后再多说一句。我见过太多人把“优秀代码”等同于“高级技巧“好像用了设计模式、函数式编程、元编程就显得更专业一样。但在我实际维护过、重构过那么多项目之后我越来越确信真正的优秀不是做复杂的事而是把复杂的事做得简单清晰。代码的最终读者除了编译器还有你的同事、你的继任者、以及半年后的你自己。我自己的代码习惯里有一条我始终坚持每次提交代码之前我会把自己当成一个完全不熟悉这个项目的人从头到尾把改动读一遍问自己”如果是我接手这段代码我能不能很快看懂并继续开发“。 如果答案是否定的不管功能是否已经实现我都会回头重构。这个习惯救过我很多次特别是在时间紧迫、赶进度的时候它强迫我保持冷静不被“先跑通再优化”的侥幸心理带着走。评判优秀代码的标准不是看它写了多少而是看它能被读懂多少不是看它今天能做什么而是看它三个月后还有没有人敢改。希望这篇文章能给你一些可以参考的思路也欢迎你在评论里聊聊你自己心中优秀代码的样子。
