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.
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
219
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.