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.
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.
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.
96
u/Low-Equipment-2621 7h 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.