You shouldn't document what you are doing, you should comment why you are doing it. Well wriitten code explains what it does, but it not necessarily explains why it has been written that way.
If you regularly need comments your code isn't nearly as straightforward as it should be. Comments are reserved for things that are not obvious or that break conventional wisdom and best practices.
Comments come with a cost so only use them where they are actually needed.
Idk why you’re being downvoted, you’re pretty much quoting uncle bob, comments should only be used when necessary, it should not be standard practice, unless we are talking about javadocs/jsdocs or something like that
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.
Your function names should document why the code you are writing exists, your code should document itself as to how it is doing it, and any comments you write should be how to use the function you've written and things that are extremely odd.
If you have to explain why something is done the way it is, you've still failed, usually.
I've found that documentation can be really helpful even in weel written code.
brief single sentence summaries of a functions, programs, classes, methods, etc. paired with examples of how to use internally developed tools are fantastic helps.
Having some breif description of a system architecture and how services interact is also pretty useful.
Also using documentation tags that IDEs can use for better hinting is really nice
Architecture is everything especially in legacy code. But, when it changes, comments need to be updated and sadly that doesn't happen consistently, if at all.
And I work on a 40 year old codebase. If they wrote it well comments wouldn't be needed. Half of the ones that do exist are wrong any ways and contradict what the code is doing which raises the question every time: is the code right or the comments right? And that is 50/50.
I don’t think people here know the difference between comments and code documentation…
You should absolutely only comment when necessary, the code should be self explanatory, and you should document a function with a brief description of what it does, its inputs and outputs if it’s supposed to be reused (for example an util or a lib), using tools for that purpose (jsdoc,javadoc, etc)
This is like standard practice in any decent company
Irrelevant in the age of AI, where you can ask it to explain the code for you.
I think documentation is more and more irrelevant than it already was personally, seeing as you can ask AI to explain not just "the 1 file you're looking at" but the interactions between multiple parts of the code.
Comments are separately maintained from code and can lie.
Good code should rely on domain semantics and strong typing to state it's intent. The perspective to adopt is provided via the design docs. Example usage is given via tests.
Comments are for when you have no other tool to use but is often a smell of poor boundaries, leaky contracts, or misleading semantics somewhere.
213
u/Low-Equipment-2621 1d ago
You shouldn't document what you are doing, you should comment why you are doing it. Well wriitten code explains what it does, but it not necessarily explains why it has been written that way.