写注释和不写注释，哪种更适应职场？

在软件开发中，代码的可读性一直是被强调重视的一个重要标准。从在学校里学编程起，提升代码可读性就被植入在我的大脑里，成为一件自然而然的事情。

然而前阵子我发了一篇文章：

程序员建议遵守的优秀编程风格

在评论区，很多人从另一个角度表达了相反的观点，也是现在网上很流行的一种说法：

“防御式编程”

即，把代码写得晦涩难懂才能增加自己在公司里的“不可替代性”。（具体言论可去原文评论区围观）

在软件和互联网行业已过了高速增长期的今天，这个话题变得越来越有争议。

今天咱们就来理理这两方的观点。

正方：代码高可读性是团队与项目的基石

代码的可读性是软件开发中不可或缺的品质。清晰的代码不仅能提高开发效率，还能为团队协作和项目维护带来长期价值。

1. 便于团队协作

在现代软件开发中，团队协作是常态。一份代码往往需要多人维护、修改或扩展。如果代码缺乏注释，变量命名含糊（如 a、b），新加入的团队成员或接手代码的开发者可能需要花费大量时间去“解谜”。清晰的注释和规范的命名（如 calculateTotalPrice 而非 calc）能大幅降低沟通成本，让团队成员快速上手。

一段函数如果有注释说明其功能、参数和返回值，其他开发者就能迅速理解其意图，而无需反复阅读代码逻辑或猜测作者的意图。

2. 降低维护成本

软件项目通常需要长期维护，代码的可读性直接影响维护的效率。清晰的代码能减少 bug 引入的概率，也便于快速定位问题。比如，命名规范的变量和函数（如 userProfileData 而非 upd）能让人一目了然，避免误解。反之，混乱的代码可能导致维护者误解逻辑，引发新的问题。

代码的可读性就像给未来的自己和团队铺路。即便开发者本人离开项目，清晰的代码也能让接手者少走弯路。

3. 提升代码质量与可扩展性

高可读性的代码往往伴随着更好的设计。规范的命名和详细的注释通常反映了开发者对代码结构的深思熟虑。例如，注释可以记录设计决策的背景，帮助后续开发者理解“为什么这样写”。这不仅提高了代码的可扩展性，也让重构或优化变得更加顺畅。

代码不仅是写给机器执行的，也是写给人阅读的。追求高可读性是对团队、对项目负责的表现。

反方：代码可读性与个人职业发展的权衡

不否认代码可读性的价值，但从个人职业发展的角度出发，过于清晰的代码可能削弱开发者的“不可替代性”。在某些场景下，故意保持代码的复杂性反而能为个人职业生涯带来优势。

1. 提高个人“不可替代性”

在竞争激烈的职场中，开发者的核心价值之一在于其专业知识和对项目的独特贡献。如果代码写得过于清晰，任何人都能轻松接手，开发者可能被认为“可有可无”。相反，复杂且难以理解的代码（例如缺乏注释、命名晦涩）会让开发者成为项目的“关键人物”，因为只有他们最了解代码的逻辑和细节。这种“不可替代性”可能在短期内为开发者争取更多的职场话语权甚至晋升机会。

例如，一个复杂的系统如果只有原作者能快速维护，公司可能更倾向于保留或重用这位开发者。

2. 节省时间与精力

编写详细的注释和遵循严格的命名规范需要额外的时间和精力。在快节奏的开发环境中，特别是在初创公司或项目赶工期时，开发者可能更关注功能实现而非代码美化。过于追求可读性可能分散注意力，延误交付时间。

与其花时间为每个函数写详细注释，不如把精力放在实现更多功能或修复 bug 上。代码只要能跑，结果正确，是否“美观”并非首要考虑。

3. 复杂并非刻意为之

在某些特定场景下，代码的复杂性是不可避免的。例如性能优化的代码可能需要使用晦涩的算法或非直观的实现方式，这类代码本身就难以做到“清晰”。强制追求可读性可能牺牲性能或其他关键目标，而开发者对这些复杂代码的掌握恰恰体现了其专业能力。

你站哪一边？

作为一个独立开发者，我没有所谓“防御式编程”的需求，但也谈不上代码规范的完美主义者。我自己的原则是：代码结构要考虑以后的扩展和维护，代码命名和注释要保证自己以后看到能够轻松理解。

对于采用“防御式编程”的程序员，我不认同但表示理解。只要你的同事、团队技术负责人、老板没有意见，那旁人也没啥好说的。

但如果你还是一个学习者，那还是建议先从编写高质量的代码做起。职场老油条们那么写是“装菜”，可不是真的菜。

对于这个问题，你怎么看？坚持编写规范代码，和在代码中“留一手”，哪种才更能构建个人的“技术护城河”？欢迎在评论区分享你的观点。

购买后可加入读者交流群，Crossin为你开启陪读模式，解答你在阅读本书时的一切疑问。

Crossin的其他书籍：

感谢转发和点赞的各位~