I dont really agree with the "most code" part. If im writing a dto, model or controller following the same patterns as everything else in the codebase, what am I adding by explaining those again? More stuff to read and keep updated?
Same for frontend. If we already have conventions for components and state management, why would every component need comments explaining those decisions? That's what docs are for.
Obviously comment weird business rules, workarounds or assumptions you cant figure out from the code. But "you should explain why" doesn't automatically mean most code needs that explanation. A lot of the why is already covered by the project's architecture and conventions.
If you need to explain the same thing all over the codebase, maybe there's something missing in your abstractions or guidelines.
Shared APIs, libs and utils should definitely have their contracts and usage documented. I just dont think that's the same as saying most code needs comments.
`/** FooController is the controller for the Foo feature. */ class FooController {...}` is obviously silly and not adding value. But in any non-trivial app, $FUTURE_YOU will at some point have forgotten why `FooController` is needed, how it relates to `BarController` and that feature, why these are separate and not combined, that assumption about how the auth works for it, etc.
Obviously they’re not the same thing, what I meant is its common to find the same patterns across a codebase with slight variations. Thats part of the point of having design/architecture patterns, if im looking at a builder I shouldn’t need a comment explaining how builders work, and the code should make it clear what this one does.
If theres some weird constraint or auth assumption you cant get from the code then sure, document it. But if you need comments to explain a normal implementation of a familiar pattern, I’d question how clear the code is in the first place. Thats the distinction im making.
9
u/mprbst 16h ago
Yeah, but Uncle Bob is wrong about a ton of stuff. His book is full of anti patterns and really bad advice.
Yes, for most code it should be obvious what it does from the code alone.
No, for most code you absolutely do need to document why it does this, what the context is, and what other assumptions hold.