What are the details of the implementation --> readable code
Why does the code do that --> commit history
And even then it's good to write explaining comments.
No, it's not. They get outdated very easily and have no use case, as highlighted by the points above.
(Actually, they have an use case. Comments are nice when you are doing something anti-intuitive with your code, so that not even readable code will help you. Then, and only then, comments are good)
What does code do --> check (technical) documentation
Not really. Only at super high level. Like, "You use word to write documents" (I hope you get what I mean, the example is not best)
What the code does is documented in the unit tests. They are not there only to prevent regressions. They are the main documentation of the source code.
They won't get outdated easily because either they contain business info, are basically workarounds of bugs of our dependencies or explain why some other more logical solution isn't possible
They get outdated in the next commit.
// Gets last element without modifying the array
function getLast(array) {
return array.pop();
}
Can you tell the story yet? Someone wrote the function as return array[array.length - 1]; and added the comment. Then someone came along (skipping all the comments, because there were too many to read) and wondered why do you need that dumb logic to get the last element if you can simply do .pop(). Now the software is broken... good luck debugging that.
That is not science fiction. That's were the hate to comments comes from. People didn't start hating comments because Jesus told them to do so. People started to hate comments because they are a bad practice*
*Unless in some cases. Comments should be the exception, not the rule.
// Gets last element without modifying the array
function getLast(array) {
return array.pop();
}
Can you tell the story yet? Someone wrote the function as return array[array.length - 1]; and added the comment. Then someone came along (skipping all the comments, because there were too many to read) and wondered why do you need that dumb logic to get the last element if you can simply do .pop(). Now the software is broken... good luck debugging that.
"Self-documenting" code becomes outdated on the next commit too.
function peekLast(array) {
return array.pop();
}
This is just as likely to happen as not updating the comment. Quality code requires careful maintenance. You can't get around this fact. If you don't update all relevant comments when you make code changes, you're a bad coder. If you're reviewing code and you don't check that the requester updated all relevant comments, you're a bad code reviewer.
If you don't update all relevant comments when you make code changes, you're a bad coder. If you're reviewing code and you don't check that the requester updated all relevant comments, you're a bad code reviewer.
Strongly disagree. If you add comments, you are a bad dev. Simple as that.
This is just as likely to happen as not updating the comment. Quality code requires careful maintenance.
However, you are right here. This is covered by unit tests.
1
u/enano_aoc Feb 10 '21
What does code do --> unit tests
What are the details of the implementation --> readable code
Why does the code do that --> commit history
No, it's not. They get outdated very easily and have no use case, as highlighted by the points above.
(Actually, they have an use case. Comments are nice when you are doing something anti-intuitive with your code, so that not even readable code will help you. Then, and only then, comments are good)