Is the laziest excuse I've come across. Like, not everyone knows everything and complex code exists, it is not hard to put in some text explaining the basics of what something does.
Like, unless you're dealing with that code everyday it's going to look like double dutch to anyone new coming to it.
I've had people say that to me before, and it is absolutely infuriating in its laziness and cop out excuse.
If someone must explain to me what code does in comments, then I think that code is bad.
Developers invented high-level programming languages for a reason. If someone writes bottom-top, unreadable code with comments, then they might as well write top-bottom, readable code without comments instead. That's what I believe self-documenting code is.
But if someone explains to me why code does what it does in comments, then that's fine. Essential complexity exists. The point is that that code is readable already, we know what it does, but not why. That's what needs an explanation in comments.
You can't read code, can you? You need some simplified text explanation of what it does. And a programming language higher than assembler is already a set of simplified text instructions. Why are you even participating in this discussion?
The documentation is a summary of the code, a quick guide to the software to more easily find your way to what you need to work with.
Are you saying that when you work with some random library, you skip their documentation and go directly to the source code? That's absurd. If you do it that way, you're wasting so much time!
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.
No. Just give the function a good descriptive name with good descriptive parameters. Keep the function simple too. If you can’t, try to refactor and see if that helps.
If you are still unable to express yourself via code, then you should use comments to guide the reader.
According to who? If I have access to the source code, which I often do, I’d rather just read the code. Chances are that if documentation exists, it’s no longer up to date.
This works as a general guideline, but sometimes you aren't able to write the code in a way that truly self-documents.
If you come back to a function after a month and need half an hour to understand it, you should probably add some comments explaining what was done and why it was done that way (in addition to considering if you should perhaps rewrite it entirely).
If your code is going to be used by third parties, you almost always need more documentation than the raw code.
Yes documentation can become obsolete. So constrain its use to cases where it actually adds clarity and commit to keeping it up to date with the evolving code.
Code is the documentation. Any other form of documentation requires additional maintenance and becomes obsolete quickly.
"Code is the documentation"
Is the laziest excuse I've come across. Like, not everyone knows everything and complex code exists, it is not hard to put in some text explaining the basics of what something does.
Like, unless you're dealing with that code everyday it's going to look like double dutch to anyone new coming to it.
I've had people say that to me before, and it is absolutely infuriating in its laziness and cop out excuse.
If someone must explain to me what code does in comments, then I think that code is bad.
Developers invented high-level programming languages for a reason. If someone writes bottom-top, unreadable code with comments, then they might as well write top-bottom, readable code without comments instead. That's what I believe self-documenting code is.
But if someone explains to me why code does what it does in comments, then that's fine. Essential complexity exists. The point is that that code is readable already, we know what it does, but not why. That's what needs an explanation in comments.
You can't read code, can you? You need some simplified text explanation of what it does. And a programming language higher than assembler is already a set of simplified text instructions. Why are you even participating in this discussion?
The comments are not for what, they are for why.
The documentation is a summary of the code, a quick guide to the software to more easily find your way to what you need to work with.
Are you saying that when you work with some random library, you skip their documentation and go directly to the source code? That's absurd. If you do it that way, you're wasting so much time!
👆 Case in point.
They sound like a great person to work with, “it’s not my fault for lack of documentation, it’s your fault for being an idiot”
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.
Ah, I see you don't optimise enough.
It should be…
Past you "I've shed so many lines and boosted processing time. It's a masterpiece. I should document this for future me because it's complex as hell."
Future you "What. The. Hell…" five minutes later "Oh, I see. I'm a fucking narcissist trying to be god of something 10 people run once a week."
all functions should at least have doc comments on them
No. Just give the function a good descriptive name with good descriptive parameters. Keep the function simple too. If you can’t, try to refactor and see if that helps.
If you are still unable to express yourself via code, then you should use comments to guide the reader.
What about exceptions raised within the function? Will you also put them in the descriptive function name? ;)
You can find them by reading the code. It’s not difficult if they’re placed at proper locations.
But a major point of a function is that you not have to read its implementation details.
According to who? If I have access to the source code, which I often do, I’d rather just read the code. Chances are that if documentation exists, it’s no longer up to date.
Modularity. Part of it is defining a proper Interface for using the hidden complexity.
Exceptions are only one example. Functions can have behavior, inner states, prior calling requirements etc… you cannot read from its mere prototype.
Do you really want everyone to read the inner code to learn that?
This risk also applies to descriptive function names. They can be poor, wrong or outdated, too.
This works as a general guideline, but sometimes you aren't able to write the code in a way that truly self-documents.
If you come back to a function after a month and need half an hour to understand it, you should probably add some comments explaining what was done and why it was done that way (in addition to considering if you should perhaps rewrite it entirely).
If your code is going to be used by third parties, you almost always need more documentation than the raw code.
Yes documentation can become obsolete. So constrain its use to cases where it actually adds clarity and commit to keeping it up to date with the evolving code.