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.
The problem is that code is language and people who write shit code tend to write shit comments, so no value is gained anyway. The sort of person who’d write good comments will most likely write good code where these comments are not needed, and when they intentionally write shit code they’d probably explain why.
So best you can hope for is that both of these people write comments about why they decided to write a comment, and hopefully the person who writes shit code improves over time.
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.
Unit tests should be the parity check for other code. Those don’t get outdated with the next refactoring where someone didn’t remember to also adjust all the comments.
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.
Why would people be better at judging if something needs a comment than at judging if something needs a better name or refactoring? Asking people to skip that judgement step and comment everything just gives you a bunch of useless boilerplate comments. That trains everyone reading that codebase to ignore comments because they are almost always useless anyway.
putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time
At least this we can 100 % agree on. Documentation should be as close as possible to the code. (I just think most of the time that place is in the name of things, not in an actual comment.)
You can’t be too obvious when writing code. Good names, good code structure, unit tests and comments are not mutually exclusive. And comments are the cheapest part of all of that. Commenting what a method does takes a fraction of the time that good code structure or unit tests take, so adding a comment is rarely not worth the effort.
Why would people be better at judging if something needs a comment than at judging if something needs a better name or refactoring? Asking people to skip that judgement step and comment everything just gives you a bunch of useless boilerplate comments. That trains everyone reading that codebase to ignore comments because they are almost always useless anyway.
Again, who is asking them to skip judgement? I am saying, do comments additionally.
And forcing programmers to do anything they don’t understand or are against will always result in useless results. I’ve seen enough unit tests that don’t actually test what the tested code does. I’ve seen nonsense comments. I’ve seen naming that “follows” the guideline but is totally useless or even wrong. I have even seen code that was implemented in spite and where the code superficially checks all the boxes but is totally terrible once you peek beyond that. Same goes for the whole process. If a programmer doesn’t care for code reviews, you get nothing by forcing the programmer to do them.
Does this mean all of these things are useless, just because programmers can purpously sabotage them and find loopholes that fit the guidelines? I don’t think so.
At least this we can 100 % agree on. Documentation should be as close as possible to the code. (I just think most of the time that place is in the name of things, not in an actual comment.)
If you can fit all the information about what something does plus all the specifics, edge cases, non-obvious things and the reason why this specific approach was taken in maximum 4 words, then yes. Otherwise comments are the way to go.
Having no documentation is fine for a small project with one dev that will get tossed in a year. But if you are making something that will actually be used for longer, than it’s not ok.
If you’re writing an explanation of what your code does then, ding ding, you’re writing code. If your code has so many side effects and garbage in it that it’s incomprehensible without an explanation then it’s shit code and I doubt you’d be able to write a comment that explains it that is not equally as shit as the code. Commenting on how shit code works cannot be trusted because the commenter has already proved they’re shit at the job by creating that shit code.
Best you can hope for is the comment contains a reason as to why the code is shit.
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.
The problem is that code is language and people who write shit code tend to write shit comments, so no value is gained anyway. The sort of person who’d write good comments will most likely write good code where these comments are not needed, and when they intentionally write shit code they’d probably explain why.
So best you can hope for is that both of these people write comments about why they decided to write a comment, and hopefully the person who writes shit code improves over time.
Unit tests should be the parity check for other code. Those don’t get outdated with the next refactoring where someone didn’t remember to also adjust all the comments.
Why would people be better at judging if something needs a comment than at judging if something needs a better name or refactoring? Asking people to skip that judgement step and comment everything just gives you a bunch of useless boilerplate comments. That trains everyone reading that codebase to ignore comments because they are almost always useless anyway.
At least this we can 100 % agree on. Documentation should be as close as possible to the code. (I just think most of the time that place is in the name of things, not in an actual comment.)
You can’t be too obvious when writing code. Good names, good code structure, unit tests and comments are not mutually exclusive. And comments are the cheapest part of all of that. Commenting what a method does takes a fraction of the time that good code structure or unit tests take, so adding a comment is rarely not worth the effort.
Again, who is asking them to skip judgement? I am saying, do comments additionally.
And forcing programmers to do anything they don’t understand or are against will always result in useless results. I’ve seen enough unit tests that don’t actually test what the tested code does. I’ve seen nonsense comments. I’ve seen naming that “follows” the guideline but is totally useless or even wrong. I have even seen code that was implemented in spite and where the code superficially checks all the boxes but is totally terrible once you peek beyond that. Same goes for the whole process. If a programmer doesn’t care for code reviews, you get nothing by forcing the programmer to do them.
Does this mean all of these things are useless, just because programmers can purpously sabotage them and find loopholes that fit the guidelines? I don’t think so.
If you can fit all the information about what something does plus all the specifics, edge cases, non-obvious things and the reason why this specific approach was taken in maximum 4 words, then yes. Otherwise comments are the way to go.
Having no documentation is fine for a small project with one dev that will get tossed in a year. But if you are making something that will actually be used for longer, than it’s not ok.
If you’re writing an explanation of what your code does then, ding ding, you’re writing code. If your code has so many side effects and garbage in it that it’s incomprehensible without an explanation then it’s shit code and I doubt you’d be able to write a comment that explains it that is not equally as shit as the code. Commenting on how shit code works cannot be trusted because the commenter has already proved they’re shit at the job by creating that shit code.
Best you can hope for is the comment contains a reason as to why the code is shit.
Found the junior dev.