06:00
antirez 拆解 Redis 源码：代码注释的九种类型
antirez on code comments: a nine-part taxonomy from Redis
antirez 以 Redis unstable 分支（32e0d237）源码为例，把代码注释拆成九类：function、design、why、teacher、checklist、guide 六类有益，trivial、debt、backup 三类可疑。他反驳“代码够好就不需要注释”的常见观点，理由有两条：注释不是在复述代码做了什么，而是补上单读局部代码拿不到的信息（为什么这样做、为什么不选看起来更自然的写法）；注释也是降低读者认知负荷的工具，scripting.c 里逐行标注 Lua 栈布局即是例证。文中逐类给出判定标准与取舍：design 注释让简化方案显得出于考量而非偷懒；teacher 注释扩大能读懂这段代码的人群；checklist 注释源于 4 bit type 这类无法中心化的设计；debt 注释（TODO/FIXME）应尽量挪到文件顶部或当场修掉；backup 注释在 Git 时代没有存在理由。适合长期维护大型系统代码库的工程师。