你喜欢注释丰富， Commit Message 详尽，还是反之？

[Had]

作为一个大龄 Ops ，喜欢简洁的代码和注释，但是写起帖子又特别碎碎念（开头就有点跑题了

本人算是古法 Vibe Coding 了，基本上除了自己的一个重构小 skill 以外，也没有安装市面上流行的 skill 。 Claude Code 和 Codex 配合其最新模型，在近两个月我前者烧了 170 亿+后者烧了 200 多亿，近四百亿 token （当然缓存命中率在 95.5%+），所以默认是怎样我还是挺清楚的，简而言之就是，

Codex 注释很少，Commit Message 你若是不稍稍加点限定，可能就只有标题，body 都没有 Claude Code 狂写注释，一个 feature 做完你不做冗余注释清理，看起来就是废话连篇，而且 Commit Message 也写的特别长

WDL本体早期使用 Claude Code ，后来因为 Opus 4.7/4.8 确实没有 GPT5.5 强，就换了 Codex 至今，基本上 CC 早期的注释痕迹已经清理的差不多了，因为是主 Coder+多 Reviewer 的结构，做为 Reviewer 的 CC 并不存在看不懂 Codex 代码的问题，但是又常常会给一些 NIT 诸如再补点注释，或者这个变更要在 Commit Message 里面体现之类

而在写大的 dogfooding 的 demo ，也就是 WDL-CHAT ，基本上都是用 CC rush 出来的，CC 默认真的会是那种高频提交+海量注释的类型，现在的结果也是我做了几轮注释清理才得到的，哪怕是这样，就看具体的文件也能看到依然有大块大块的注释在里面

不知道诸位喜欢哪种风格？

[Nasdaq]

Claude behind me

[jko123]

“古法 vibe coding”，“两个月烧了 370 一 token”，这真的是古法吗😲

[ronman]

你这算古法？！

[canyue7897]

不看代码
不管注释
完成任务
省 token 省钱
就是我的目标

[darksword21]

直接用 emacs 的 commit message 规范

[wiekern]

我倾向于代码内注释，commit 消息相对简洁一些，当然要能说明提交的主要改动，不能为了精简而精简。如果你希望有 commit 消息来生成 changelog 文档，那在 commit body 里写详细一点也 OK 吧，还是要适合自己。你可以写规则让 AI 提交代码时遵守

[Had]

@jko123
@ronman
古法 vibe coding 指不用复杂的 skills:)

[Had]

@wiekern 写规则就不够古法了:)
不过 commit message 写全的意义也在于让 llm 根据提交进行阶段性总结时，不用去一个提交一个提交去 diff

[ershierdu]

95%的 Claude code 注释都是没必要的，太啰嗦了。

再进一步讲，注释是模型基于你的 prompt 生成的，那理论上另一个模型基于同样的 prompt 也能理解代码？所以真正有价值的是把人的输入保留下来，通过注释或文档

[Had]

@ershierdu 我觉得稍稍有点偏差 cc 是很主动写注释的，它和 user prompt 没啥关系？
另外其实代码都能理解 codex 写的 cc 也能理解 但是它就是建议你再补点注释或者解释性内容
好代码应该是自解释的

[unused]

注释也算 token 哦

[shitshit666]

我觉得代码自解释最重要，注释只写'为什么'而不是'是什么'，commit message 简洁说明改动即可。

[dwhh]

@ronman 他说的是古法 vibe coding ，不是古法 coding 。。。

[weiwenhao]

我觉得注释太多是有点费 token 的，费 token 还好，但是浪费 context 是大问题，context 一大整体效果就会变差。

[lucays]

除了关键部分业务需求一行注释啥的
什么大段的函数注释类注释本来就没有用，骗骗自己得了，AI 出来了彻底没用了，浪费 token

[defaw]

Commit message 还是尽量详细一点比较好，因为对于 AI 来说，如果他不能从 commit message 里面拿到它的信息的话，它就只能制造非常多轮对话(工具调用)来寻找你所说的信息。这个不仅是消耗上下文，而且每一轮对话都会收每一轮对话的钱。

[mogita]

这是我的全局 CLAUDE.md 里关于代码注释的一条，加上之后注释再也不废话了。

- Comments document the contract a caller must respect, not the internal mechanism, downstream effects, or motivating examples.

[mogita]

咋发出去了。提交信息也可以类似的方式简单约束一下，不然全是小作文。

[craftsmanship]

@canyue7897 +1 请问目前的最佳实践是什么

[clemente]

写 changlog 就行

[OneLiteCore]

大多数时候 Commit Message 基本没啥人看，代码的话也只有重构或者出问题的时候才去看，此时代码内的注释作用更大些，但也不是说注释越多越好。个人感觉代码内的注释只要解释清楚为什么这么做以及这么做的用处是啥，那就算足够了。

[THESDZ]

不是注释本身多少，而是代码本身的就该自解释
而自解释也有讲究，如：方法名完备，参数名正确，主方法行数少，但逻辑清晰，避免 if/else （用适配器或者 if return ）
注释只做补充，比如明明可以用 bitmap 来压缩内存，但出于 xxx 考虑不压缩等，类似这种的。

[IMengXin]

注释丰富，Commit Message 简洁
注释是为了让以后的自己能看懂，Commit Message 是为了以后来查哪个功能是哪天更新的

[kristofer]

不管注释，那是我的 AI 该想的问题。

[ximaoyang]

引用自 martin 的重构
1. 注释是一种信号,不是奖励
当你发现自己需要写注释才能让一段代码被理解时,Fowler 认为第一反应不该是"好,那就写清楚点",而应该是问:为什么这段代码不能自己说清楚? 通常答案是——需要重构了。
2. "需要注释"是 Extract Function 的触发器
书里明确把这个当作重构信号:如果你想写注释来解释一个代码块在做什么,那就把这个代码块提炼成一个函数,函数名就是那句注释。

[aarontian]

commit message 可以在 AGENTS.md/CLAUDE.md 约束，一行多行都可以。

但就注释风格我更喜欢 codex ，claude 非常热衷在注释或者文档里加废话。

一个可能不够典型的例子，比如做需求往公共 proto 仓库里加接口，它会把需求初始讨论过的“给 xx 团队调用”这种推断写进去，让我很难理解其动机，劝阻后过一会补充字段时又加，不专门制止，加着加着就会变成加一个无关痛痒的字段先写两三行注释，一个原本通用化设计的字段它一定要用语言限定到某某场景使用。

有点像跟一些看起来不怎么聪明的程序员/架构师交流，说事没重点，喜欢从盘古开天辟地开始讲起。我暂时也很难定一个清晰的规则说注释应该写明哪些、哪些描述不应该进注释，但这方面 gpt 明显要聪明不少

[yanaraika]

注释需要描述代码中不清晰的意图

干净代码+简洁注释 > 复杂代码 + 大量注释 > 干净代码 + 大量注释 > 复杂代码 + 少量注释

[doraemonki]

AGENTS.md 第一句
Explain "Why", not "What": Use comments to explain design rationale, business logic constraints, or non-obvious trade-offs. Code structure and naming should inherently describe the "what."

[swananan]

这个不是二选一，而是确保代码尽量可以清晰的传递开发者的意图，注释和 commit message 是代码无法展示信息的补充。举个例子，开发者可能做了一些 trade off ，放弃了一些方案，但是代码肯定无法体现这些细节，这个时候注释或者 commit message 就需要出场把这部分信息给表达出来。

代码、注释和 commit message 要尽量表达出写代码人的思考，让后续具备相关领域知识的人能够看明白当时的上下文，这样所谓屎山代码，或者说不明所以又不敢乱动的地方才会尽可能少出现。