The code shows what happens. But comments should explain why it was done this way.
Sometimes the code started simple and readable, till you ran into a weird edge case a year ago. Now the code no longer looks as obvious and another developer might scratch their head when they read over it. A small comment can help out there quite a bit.
Or you’re doing something stupid in code not because you want to, but because management forced you to. So you put a comment there that the code isn’t wrong, management wanted that behavior.
The why can usually be found in Git and issue trackers. Just look at the history of the file to get some decent clue about why a piece of code was programmed in a certain way.
That works for newer projects, but on older projects there’s a dozen commits for any given line and a handful of Jira tickets that have something to do with it, but none that say “Change exactly this”. A comment why you made an interesting design decision costs a lot less time than trying to unwrap the commit history… Especially when you can’t even find a clue on why this was done as the commit might simply be “Implemented feature XY”
I think comments should be a last resort when all other methods are inadequate. Proper git commit logs have helped me many times to understand why a certain thing is needed.
Git logs don’t need maintenance either. They always tell what was true when the code was written. Comments need maintenance, and are often difficult to keep updated.
You can write a detailed comment about the whys of a particular function, only for it to become outdated in weeks when the functionality has changed.
I still haven’t found a proper command or tool to do a multi-commit git blame.
Like I want to know who changed the logic in this line. But the last commit was a format refactor. And the commit before that just changed a tiny detail. So now I’m digging through the entire file history just to find the spot where this one line was introduced or actually changed.
I usually use the GUI in IntelliJ for those kind of purposes, but any other GUI might do. Then I perform a manual binary search to find the commit I want.
The code shows what happens. But comments should explain why it was done this way.
Sometimes the code started simple and readable, till you ran into a weird edge case a year ago. Now the code no longer looks as obvious and another developer might scratch their head when they read over it. A small comment can help out there quite a bit.
Or you’re doing something stupid in code not because you want to, but because management forced you to. So you put a comment there that the code isn’t wrong, management wanted that behavior.
The why can usually be found in Git and issue trackers. Just look at the history of the file to get some decent clue about why a piece of code was programmed in a certain way.
That works for newer projects, but on older projects there’s a dozen commits for any given line and a handful of Jira tickets that have something to do with it, but none that say “Change exactly this”. A comment why you made an interesting design decision costs a lot less time than trying to unwrap the commit history… Especially when you can’t even find a clue on why this was done as the commit might simply be “Implemented feature XY”
I think comments should be a last resort when all other methods are inadequate. Proper git commit logs have helped me many times to understand why a certain thing is needed.
Git logs don’t need maintenance either. They always tell what was true when the code was written. Comments need maintenance, and are often difficult to keep updated.
You can write a detailed comment about the whys of a particular function, only for it to become outdated in weeks when the functionality has changed.
I still haven’t found a proper command or tool to do a multi-commit git blame.
Like I want to know who changed the logic in this line. But the last commit was a format refactor. And the commit before that just changed a tiny detail. So now I’m digging through the entire file history just to find the spot where this one line was introduced or actually changed.
If you have any tips for that, I’m all ears.
I usually use the GUI in IntelliJ for those kind of purposes, but any other GUI might do. Then I perform a manual binary search to find the commit I want.