I’ve always felt this argument works best in small, stable codebases with low team churn.
Self-documenting code is a great goal, but in real systems the why often matters more than the what, and that context rarely survives in variable names alone.
In my experience, comments age badly when they restate code, but they age quite well when they capture constraints, trade-offs, or historical decisions.
The real smell isn’t comments, it’s comments compensating for unclear design.
alexpadula•8h ago
Love it! I agree. A large codebase, complex I feel like we don’t want less or no comments, we don’t want useless comments but comments that are up to date and useful to the reader. Sure you can follow code but code can stink too.
runtimepanic•9h ago
alexpadula•8h ago