当代码成迷宫，聪明开发者会画地图
When code is a maze, smart developers make maps
现代代码早已告别了混乱的“意大利面代码”，却陷入了更令人头疼的“意大利饺子代码”——组件高度解耦，导致逻辑难以追踪。面对这种代码迷宫，盲目探索往往耗时巨大。Simon Smart 提出，聪明的开发者不会让经验随时间遗忘，而是通过注释留下路标，通过文档绘制地图。无论是解释“为什么”的注释，还是使用 Mermaid 和 draw.io 绘制的系统图，这些看似需要维护的“地图”，实则是减少团队在迷宫中迷路时间的关键投资。
聪明的开发者不会让自己学到的东西被遗忘，他们会留下路标帮助他人导航，他们会绘制地图来分享自己的经验。
HN 评论区
45- tromp
当代码成迷宫 描述了我 1988 年的 IOCCC 参赛作品 [1]
char*M,A,Z,E=40,J[40],T[40];main(C){for(*J=A=scanf(M="%d",&C);
-- E; J[ E] =T
[E ]= E) printf("._"); for(;(A-=Z=!Z) || (printf("\n|"
) , A = 39 ,C --
) ; Z || printf (M ))M[Z]=Z[A-(E =A[J-Z])&&!C
& A == T[ A]
|6<<27<rand()||!C&!Z?J[T[E]=T[A]]=E,J[T[A]=A-Z]=A,"_.":" |";}
- jorisw
聪明的开发者不会写出迷宫。
> 在代码中，注释是我们的路标
不。命名和优秀的架构才是。直观的文件夹树。简洁的文档。清晰的关注点分离，使得命名足以说明一切。
你需要多少注释来“绘制”代码地图，就证明你做得有多糟糕。
- jarofgreen
> 通常将注释保持在单行，不要换行——如果注释有用，开发者会滚动查看；如果没用，他们可以轻松跳过。
不同意。对我来说，这听起来像是阅读注释的巨大障碍。通常认为，限制宽度的列文本更易阅读，让你的注释更容易读。尤其是，我可能是在一个宽度受限的窗口中打开代码，因为这就是我期望代码呈现的样子。
- lintfordpickle
我不同意这篇文章的整体观点。我不会说注释永远没用，因为它们确实有用。但一旦冗长的注释成为常态，人们（尤其是现在的 LLM）就会过度使用它们，导致代码变得不必要地晦涩难懂。而且关于维护性的观点是真实的。
文章本身也有几句“废话”：
> “根据情况结合使用行内注释和独立注释”
这不就是所有类型的注释吗？
- jdw64
听起来不错。我已经数不清自己造过多少个迷宫了。就叫我“迷宫建筑师”吧。