I strongly disagree with the comments. “The code is the documentation” was a dumb joke about being to lazy to write documentation, not a best practices guideline.
Proper naming is good, but there are a lot of issues with not commenting code. Obviously it’s dumb to comment every line, but it’s really useful to comment functions/methods, because otherwise you never know if something’s a bug or a non-obvious feature. Comments act as a parity check to the code, since they tell you what the dev who wrote the code wanted the code to do.
Also, everone thinks they write good, clean and obvious code. Hardly anyone purpously writes bad, hacky code. Yet if you look at code you wrote a year ago, or code someone else on your team wrote, it’s full of non-obvious hacks. That means, people constantly misjudge the obviousnes of their code. Comments should be put on anything that could maybe be non-obvious.
And putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time (unless you put a link to the specific page of the documentation in a comment in the code), because documentation that you don’t directly see without effort will not be found and not be read.
“Code is the documentation” is the paradise we all want to be someday. But some people use that as an excuse to not write the documentation explaining why this piece of code exists in the first place. I find it extremely annoying when there is not a single architecture diagram is available and someone tell me to figure it out by reading his/her spaghetti code.
I strongly disagree with the comments. “The code is the documentation” was a dumb joke about being to lazy to write documentation, not a best practices guideline.
Proper naming is good, but there are a lot of issues with not commenting code. Obviously it’s dumb to comment every line, but it’s really useful to comment functions/methods, because otherwise you never know if something’s a bug or a non-obvious feature. Comments act as a parity check to the code, since they tell you what the dev who wrote the code wanted the code to do.
Also, everone thinks they write good, clean and obvious code. Hardly anyone purpously writes bad, hacky code. Yet if you look at code you wrote a year ago, or code someone else on your team wrote, it’s full of non-obvious hacks. That means, people constantly misjudge the obviousnes of their code. Comments should be put on anything that could maybe be non-obvious.
And putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time (unless you put a link to the specific page of the documentation in a comment in the code), because documentation that you don’t directly see without effort will not be found and not be read.
“Code is the documentation” is the paradise we all want to be someday. But some people use that as an excuse to not write the documentation explaining why this piece of code exists in the first place. I find it extremely annoying when there is not a single architecture diagram is available and someone tell me to figure it out by reading his/her spaghetti code.