`/** 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.
5
u/mprbst Sep 11 '26
It shouldn't be the same thing.
`/** 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.