Please please please, do not always write comments. Try to write code that does not need comments whenever possible. Proper variable, class and method names go a long way. If you think a block of code needs a comment, turn it into a method and give it a proper name instead.
Comments should be a last resort for cases where making the code self explanatory is not possible, and those should be rare.
About optimization:
Optimal code is code that fulfills it's purpose without observable issues.
If you try to make something faster without any prior complaints or measurements indicating that it being slow is an actual issue, you are not optimizing, you are just engaging in mental masturbation.
For my current job we've all agreed to take the approach of not writing comments that say what the code does, but why you did something the way you did. Probably about 90% of our code is uncommented because it just doesn't need to be, but every once in a while you have to do something out of the ordinary to get the desired behavior, and explaining why you made the weird decision you did is infinitely more helpful.
This exactly. I love this approach to commenting and use it all the time. I also like to write doc-comments wherever possible; it’s saves time and makes working on an unfamiliar part of the codebase much easier.
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.
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.)
The problem here is that every junior programmer thinks they write clean code when they really really don't. Often I find the act of writing comments makes you go back to the code and clean things up, so it's still worth encouraging comments.
I just get AI to write my comments lol. I'll paste the function or component and tell it to write comments in tsdocs format and it works great every time (I will also add to it sometimes of course).
Don't get me wrong, I also write clean code with good function and variable naming, but I find comments are also useful for a few reasons; they make the code even more quickly readable, they can explain why the code is the way that it is, and my favorite reason, they make it so when you hover over a reference to the commented item in an ide you get an explanation of exactly what the code does and what it expects without having to find and read the code itself
This is the way. In 'some' cases comments are perfectly fine. Like when you need to document 'why' something was done the way it was our to link to a specific piece of documentation.
When you start commenting 'what' the code does, you code is not self explanatory enough. And those comments will get outdated and need refactoring too. Just more unnecessary work.
If you think a block of code needs a comment, turn it into a method and give it a proper name instead.
Really depends. Yes, if someone doesn't get what's wrong with this statement, they should. But you shouldn't wrap something in a method all the time just because. Sure, maybe you can make it an inline method, but usually, a method call takes time, and while it's not a lot of time, in constrained or complex system that can accumulate. A lot. Sure, the compiler might optimize stuff away, but don't just go blindly trusting your compiler.
Sure, a method call for something that gets called once a second is not a problem. But when you suddenly have thousands and thousands of method calls when say, you click a button, which calls method x which calls method x1 which calls y1 and y2 which call z1-10 and so on, then the method calls can suddenly turn into a problem.
Maybe not on a fast, modern device, but on an older or more constrained device. If your code never runs on there, sure, don't bother.
Yeah, this grinds my gears. I use to comment my code when I'm working on my personal projects, then at the office I have to waste time trying to decipher my boss's code because he won't comment absolutely anything.
That plus the ridiculous deadlines means that I don't have time to comment my own code, fast forward several months later without working on a particular project and now I have to decipher his and my own code.
One day he actually had the nerve to say to me: 'Yeah, you should comment your code'. How I refrained of commiting murder that day I don't know.
I just want variable names to be consistent. You do variableName then 5 lines down Jerry does a typo VariableNames and so Bob makes a function that's gets it's value from variableName and sets VariableNames with it 100 lines down because bobs tired and wants to go home.
Don't write comments for someone else. Write comments for yourself because you might write a million lines of code and then be told you need to do something to this now ancient legacy code at 3am because some nightmare scenario happens and you need to get it fixed and deployed before they'll let you go back to sleep.
why would you use a synthesized picture for this meme? Couldn't you just pick a random, even a lame image from google? You had to make it nonsensical, lifeless and discomforting
I wish, companies just expect you to write garbage code as quick as possible, only to create tens of bugs afterwards that will take way more time than it would if they had left you enough time to do it correctly
That's what people with tribal knowledge like to say when they are really saying "I'm the only one who knows how this works, it 's hard to get rid of me."