Think back to the last time you looked at an unfamiliar block of code. Did you immediately understand what it was doing? If not, you’re not alone – many software developers, including myself, find it challenging to grasp unfamiliar code quickly…
And sometimes code is not the right medium for communicating domain knowledge. For example, if you are writing code the does some geometric calculations, with lot of trigonometry, etc. Even with clear variable names, it can be hard to decipher without a generous comment or splitting it up into functions with verbose names. Sometimes you really just want a picture of what’s happening, in SVG format, embedded into the function documentation HTML.
Yeah. I advocate for self explanatory code, but I definitely don’t frown upon comments. Comments are super useful but soooo overused. I have coworkers that aren’t that great that would definitely comment on the most basic if statements. That’s why we have to push self explanatory code, because some beginners think they need to say:
//prints to the console
console.log("hello world");
I think by my logic, comments are kind of an advanced level concept, lol. Like you shouldn’t really start using comments often until you’re writing some pretty complex code, or using a giant codebase.
Sometimes when I don’t leave comments like that, I get review comments asking what the line does. Code like ThisMethodInitsTheService() with comments like “what does this do?” in the review.
So now I comment a lot. Apparently reading code is hard for some people, even code that tells you exactly what it does in very simple terms.
Fair. I guess in this case, it’s a manner of gauging who you’re working with. I’d much rather answer a question once in a while than over-comment (since refactors often make comments worthless and they’re so easy to miss…), but if it’s a regular occurrence, yeah it would get on my nerves. Read the fuckin name of the function! Or better yet go check out what the function does!
Worse, refactors make comments wrong. And there is nothing more annoying then having the comment conflict with the code. Which is right? Is it a bug or did someone just forget to update the comments… The latter is far more common.
Comments that just repeat the code mean you now have two places to update and keep in sync - a pointless waste of time and confusion.
Agreed.
And sometimes code is not the right medium for communicating domain knowledge. For example, if you are writing code the does some geometric calculations, with lot of trigonometry, etc. Even with clear variable names, it can be hard to decipher without a generous comment or splitting it up into functions with verbose names. Sometimes you really just want a picture of what’s happening, in SVG format, embedded into the function documentation HTML.
Yeah. I advocate for self explanatory code, but I definitely don’t frown upon comments. Comments are super useful but soooo overused. I have coworkers that aren’t that great that would definitely comment on the most basic if statements. That’s why we have to push self explanatory code, because some beginners think they need to say:
//prints to the console console.log("hello world");I think by my logic, comments are kind of an advanced level concept, lol. Like you shouldn’t really start using comments often until you’re writing some pretty complex code, or using a giant codebase.
Sometimes when I don’t leave comments like that, I get review comments asking what the line does. Code like
ThisMethodInitsTheService()with comments like “what does this do?” in the review.So now I comment a lot. Apparently reading code is hard for some people, even code that tells you exactly what it does in very simple terms.
Fair. I guess in this case, it’s a manner of gauging who you’re working with. I’d much rather answer a question once in a while than over-comment (since refactors often make comments worthless and they’re so easy to miss…), but if it’s a regular occurrence, yeah it would get on my nerves. Read the fuckin name of the function! Or better yet go check out what the function does!
Worse, refactors make comments wrong. And there is nothing more annoying then having the comment conflict with the code. Which is right? Is it a bug or did someone just forget to update the comments… The latter is far more common.
Comments that just repeat the code mean you now have two places to update and keep in sync - a pointless waste of time and confusion.
TempleOS: Hold my communion wine