If your code needs comments, it’s either because it’s unnecessarily complex/convoluted, or because there’s more thought in it (e.g. complex mathematic operations, or edge-cases etc.).
Comments just often don’t age well IME, and when people are “forced” to read the (hopefully readable) code, they will more likely understand what is really happening, and the relevant design decisions.
Exactly that!
Everyone can See “what” is happening, thr code is right there. But the code usually doesn’t tell you “why” that is happening - good comments help understand the authors intent and give context, so you don’t have to guess.
Good comments should explain the things that are not obvious.
Good comments more than once prevented me from accidentially undoing a fix.
I was running out of time so this it’s mostly copied from (stack overflow url)
refactor when time allows
This is a side effect of doing lots of tiny websites , microcontroller code and mini web apps for under budgeted marketing projects with constantly changing designs that don’t need to last too long.
comments are for explaining why you did things a certain way
A while back I spent more than a year modifying my company’s iOS apps so that they would work properly with VoiceOver (Apple’s screen reader technology for blind people) and be compliant with FCC regulations for accessibility (and save us from $1 million per month fines lol). The thing about VoiceOver is that it’s bizarrely buggy (or was - maybe they’ve fixed the problems since then) and even when I didn’t run into VO bugs, the way that developers tended to architect these apps often made getting them to behave properly with VoiceOver extremely difficult.
I often had to resort to very strange hacks in order to get things to work, and I would always leave comments explaining what I had done for this. My manager was one of the new breed who not only thought comments were unnecessary in ALL cases but also thought comments were a “code smell” and indicative of professional incompetence on the part of anyone who used them. Whenever he reviewed my code, he would leave in the hacks (after trying and failing to fix the problems without them) but remove my comments. This resulted in many cases later of developers contacting me to ask me why some bizarre bit of code was in the app in the first place. I always referred them to my manager with an NMP (Not My Problem any more).
I think most people fail to understand what code smell really is. They think code smell means bad code. A code smell is actually an indication that something else might be bad with the code. The code smell itself might not be bad.
So when a code smell appears, it means you should identify the reason it exists and potentially fix it. In this case the bad code is a buggy external library, which is difficult for you to fix. Therefore, leaving the “code smell” is the best course of action.
Your manager was in the wrong and you were right to write comments.
This resulted in many cases later of developers contacting me to ask me why some bizarre bit of code was in the app in the first place. I always referred them to my manager with an NMP (Not My Problem any more).
I hope this isn’t a real story. It would have taken you just as long to refer them to the commits with your comments still in, and run a git blame to show your manager took them out. Instead you just make yourself look unhelpful and incompetent.
If you’re working with others, even simple code benefits from comments explaining what it’s intended to do. Sure you can read code and get a good idea of what it seems to do, but having a quick statement from the author enables you to work faster. And if you find a mismatch between the comment and the code, it’s a smell that could mean a bug.
And for methods and functions it’s particularly helpful to have a description at the top. Many IDEs will pop this up when you’re using the method, so you can quickly confirm that it’s appropriate for your needs and get your arguments in the right order.
That’s like saying a book’s synopsis shouldn’t exist because you can just read the whole book. Sometimes comments can save you a lot of time and point you in the right direction.
Nah, it’s not, code is modular (IME should be kinda tree-structured), a book is linear.
So the API should be in your analogy the synopsis. And I haven’t said, that there shouldn’t be any comments. E.g. doc-comments above functions, explaining the use-cases and showing examples are good practice.
I have such a love-hate relationship with that video. On the whole, I think that video is bad and should be taken down. The creator is arguing against a very specific type of commenting but is harassing comments in all forms. It even addresses as such with a 20 second blurb 2/3 of the way into video distinguishing between “documentation comments” - but doesn’t really provide any examples of what a good documentation comment is. Just a blurred mention of “something something Java Doc something something better code leads to better documentation” but doesn’t elaborate why. It’s a very devious problem in that I don’t feel like any particular claim in the video is wrong, but taken within the context of the average viewer, (I teach intro. comp. sci courses and students LOVE to send this video and similar articles to me for why they shouldn’t have to comment their spaghettified monstrosities), and the inconsistent use of comments vs. code duplication vs. documentation, the video seems problematic if not half-baked. In fairness, it is great advice for someone who has been working in the industry for 15 years and still applies for junior positions within the same company - but I can’t imagine that was the target audience for this video. In my experience, anyone who has been programming on a large-ish project for more than 6 months can reach the same conclusions as this video.
I’m from the camp that thinks if you’re trying to make a case (about any subject), you should start with your strongest point and work to your weakest point. Every argument I’ve ever seen against code comments starts off with the weakest imaginable points. Usually the first point made is sample code like “x = x + 1” with the absurdly unnecessary comment “add 1 to x” - as if that’s ever something that pro-comment programmers do. This video at least started off with a novel weak point (somebody using a comment with a magic number instead of making it a constant) although it’s just as weak as the “x = x + 1” argument.
Sounds very theoretical, my experience working on some 40 year old software full of business logic, where customer A got some feature but customer B needs it to work slightly different. Aka something approaching spaghetti.
Regarding old comments I have several times used ~15 year old comments by the original author, close to the actual code to piece together the use of that code, and if I can add my fix there.
In this setting You write comments for yourself, when you in two years need to fix a bug in the new code caused by your old code. And for the next developer that will look at your code decades after you left the company.
Sometimes you, against good practice, comment out a section, with a note why, because you know this will have to be re-enabled in a few months.
This mindset is good, but unfortunately enforces bad programmers to leave their undocumented code in critical places where someone eventually has to figure out what the hell they were doing or refactor the whole damn thing because they got promoted to middle-management and can’t be bothered to remember why they even wrote it.
This is something that is always stated by people who are opposed to comments, but I’ve never seen any such thing in practice. If being mislead by incorrect comments is so common, there should be a bunch of stories around about disasters caused by them - and I’ve never read a single such story.
If the comments tell you “what” happens, then yes, they can geht outdated fast. The details of how something works can change quickly.
But comments documenting “why” something is done (a certain way) - explaining the intent - are probably valid for mich longer.
In the best case comments aren’t viewed as something that is seperate from the code, but part of it. So that if someone changes the code, the comments has to be checked aswell (if the explanation of “why” something is done actually changed).
Or just name the variable delaySeconds if you really want to store it as an int. Bonus is that every use of the variable perfectly communicates what it is.
One day you will inherit a code base so bad that you’ll end up commenting old code just to make sense of it for yourself because nobody in the company has touched in a couple years and the last people that did no longer work there. It will be dangerously coupled, if you make the right change somewhere it will break everything else. It will be true spaghetti code where you spend 30 min just following a code path to figure out what and why an input into a function needs to be what it is to able to come out of another function in an exact format for anything to work.
Your so called comment standards and principals are fine if you are building something from the ground up, but the other 95% of the time, you do what you gotta do because your were blessed with a turd that is impossible to polish.
One day you will inherit a code base so bad that you’ll end up commenting old code
Will not be the case, I won’t take a job, where I have this situation (or I’ll quit pretty quickly)…
Yeah my “comment standards” (btw. as others mentioned here, I was unprecise/unlucky with the choice of words, I meant “comment the why” or doc-comments totally fine and should be aimed)
Your so called comment standards and principals are fine if you are building something from the ground up
Yes that was also targeted with my comment. But what you’re referring to is just missing documentation, and I think this should be done on a higher level. The “comment why” rule applies for spaghetti code non-the-less…
Rare?
Where do you guys work that all you do is write basic AI generatable code?
The only thing I can think is that you are a bunch of freelance devs who never have to maintain anything or add functionality to old code.
Either that or you are all new and are just full of theoretical bullshit that you read on the internet.
Or you’re stuck within the confines of a horrible legacy system which the business will not allow you the time to refactor/rewrite but still want your code to be somewhat readable.
But in general, I agree with your argument. When writing from scratch or improving reasonably well designed code, often documentation could be replaced by breaking it up into another function or naming variable better. It’s a bit of a code smell for violating the SRP.
philm@programming.dev 10 months ago
Yeah, but unironic…
If your code needs comments, it’s either because it’s unnecessarily complex/convoluted, or because there’s more thought in it (e.g. complex mathematic operations, or edge-cases etc.). Comments just often don’t age well IME, and when people are “forced” to read the (hopefully readable) code, they will more likely understand what is really happening, and the relevant design decisions.
Good video I really recommend: www.youtube.com/watch?v=Bf7vDBBOBUA
Pickle_Jr@lemmy.dbzer0.com 10 months ago
Yeah, another way I’ve heard it phrased is comments are for explaining why you did things a certain way, not for explaining what it’s doing.
heikomat@lemmy.world 10 months ago
Exactly that! Everyone can See “what” is happening, thr code is right there. But the code usually doesn’t tell you “why” that is happening - good comments help understand the authors intent and give context, so you don’t have to guess.
Good comments should explain the things that are not obvious.
Good comments more than once prevented me from accidentially undoing a fix.
nilloc@discuss.tchncs.de 10 months ago
Yup my comments are generally along the lines of:
This is a side effect of doing lots of tiny websites , microcontroller code and mini web apps for under budgeted marketing projects with constantly changing designs that don’t need to last too long.
ChickenLadyLovesLife@lemmy.world 10 months ago
A while back I spent more than a year modifying my company’s iOS apps so that they would work properly with VoiceOver (Apple’s screen reader technology for blind people) and be compliant with FCC regulations for accessibility (and save us from $1 million per month fines lol). The thing about VoiceOver is that it’s bizarrely buggy (or was - maybe they’ve fixed the problems since then) and even when I didn’t run into VO bugs, the way that developers tended to architect these apps often made getting them to behave properly with VoiceOver extremely difficult.
I often had to resort to very strange hacks in order to get things to work, and I would always leave comments explaining what I had done for this. My manager was one of the new breed who not only thought comments were unnecessary in ALL cases but also thought comments were a “code smell” and indicative of professional incompetence on the part of anyone who used them. Whenever he reviewed my code, he would leave in the hacks (after trying and failing to fix the problems without them) but remove my comments. This resulted in many cases later of developers contacting me to ask me why some bizarre bit of code was in the app in the first place. I always referred them to my manager with an NMP (Not My Problem any more).
magic_lobster_party@kbin.social 10 months ago
I think most people fail to understand what code smell really is. They think code smell means bad code. A code smell is actually an indication that something else might be bad with the code. The code smell itself might not be bad.
So when a code smell appears, it means you should identify the reason it exists and potentially fix it. In this case the bad code is a buggy external library, which is difficult for you to fix. Therefore, leaving the “code smell” is the best course of action.
Your manager was in the wrong and you were right to write comments.
zalgotext@sh.itjust.works 10 months ago
I hope this isn’t a real story. It would have taken you just as long to refer them to the commits with your comments still in, and run a git blame to show your manager took them out. Instead you just make yourself look unhelpful and incompetent.
floofloof@lemmy.ca 10 months ago
If you’re working with others, even simple code benefits from comments explaining what it’s intended to do. Sure you can read code and get a good idea of what it seems to do, but having a quick statement from the author enables you to work faster. And if you find a mismatch between the comment and the code, it’s a smell that could mean a bug.
And for methods and functions it’s particularly helpful to have a description at the top. Many IDEs will pop this up when you’re using the method, so you can quickly confirm that it’s appropriate for your needs and get your arguments in the right order.
philm@programming.dev 10 months ago
Don’t get me wrong comments != documentation (e.g. doc-comments above function/method).
I probably was a bit unprecise, as others here summed up well, it’s the why that should be commented.
potustheplant@feddit.nl 10 months ago
That’s like saying a book’s synopsis shouldn’t exist because you can just read the whole book. Sometimes comments can save you a lot of time and point you in the right direction.
BaardFigur@lemmy.world 10 months ago
Comments also helps explaining why certain non-obvious decisions are made. E.g. a workaround for a bug in a library
philm@programming.dev 10 months ago
Nah, it’s not, code is modular (IME should be kinda tree-structured), a book is linear.
So the API should be in your analogy the synopsis. And I haven’t said, that there shouldn’t be any comments. E.g. doc-comments above functions, explaining the use-cases and showing examples are good practice.
potustheplant@feddit.nl 10 months ago
Books can be modular as well (ever heard of “Rayuela” by Cortazar?) But that’s beside the point. The analogy is fine and it works.
DaleGribble88@programming.dev 10 months ago
I have such a love-hate relationship with that video. On the whole, I think that video is bad and should be taken down. The creator is arguing against a very specific type of commenting but is harassing comments in all forms. It even addresses as such with a 20 second blurb 2/3 of the way into video distinguishing between “documentation comments” - but doesn’t really provide any examples of what a good documentation comment is. Just a blurred mention of “something something Java Doc something something better code leads to better documentation” but doesn’t elaborate why. It’s a very devious problem in that I don’t feel like any particular claim in the video is wrong, but taken within the context of the average viewer, (I teach intro. comp. sci courses and students LOVE to send this video and similar articles to me for why they shouldn’t have to comment their spaghettified monstrosities), and the inconsistent use of comments vs. code duplication vs. documentation, the video seems problematic if not half-baked. In fairness, it is great advice for someone who has been working in the industry for 15 years and still applies for junior positions within the same company - but I can’t imagine that was the target audience for this video. In my experience, anyone who has been programming on a large-ish project for more than 6 months can reach the same conclusions as this video.
ChickenLadyLovesLife@lemmy.world 10 months ago
I’m from the camp that thinks if you’re trying to make a case (about any subject), you should start with your strongest point and work to your weakest point. Every argument I’ve ever seen against code comments starts off with the weakest imaginable points. Usually the first point made is sample code like “x = x + 1” with the absurdly unnecessary comment “add 1 to x” - as if that’s ever something that pro-comment programmers do. This video at least started off with a novel weak point (somebody using a comment with a magic number instead of making it a constant) although it’s just as weak as the “x = x + 1” argument.
BeigeAgenda@lemmy.ca 10 months ago
Sounds very theoretical, my experience working on some 40 year old software full of business logic, where customer A got some feature but customer B needs it to work slightly different. Aka something approaching spaghetti.
Regarding old comments I have several times used ~15 year old comments by the original author, close to the actual code to piece together the use of that code, and if I can add my fix there.
In this setting You write comments for yourself, when you in two years need to fix a bug in the new code caused by your old code. And for the next developer that will look at your code decades after you left the company.
Sometimes you, against good practice, comment out a section, with a note why, because you know this will have to be re-enabled in a few months.
Report from the frontlines…
astraeus@programming.dev 10 months ago
This mindset is good, but unfortunately enforces bad programmers to leave their undocumented code in critical places where someone eventually has to figure out what the hell they were doing or refactor the whole damn thing because they got promoted to middle-management and can’t be bothered to remember why they even wrote it.
magic_lobster_party@kbin.social 10 months ago
Chances are that the comments quickly turn out of date and become incorrect. Misleading comments is worse than no comments.
ChickenLadyLovesLife@lemmy.world 10 months ago
This is something that is always stated by people who are opposed to comments, but I’ve never seen any such thing in practice. If being mislead by incorrect comments is so common, there should be a bunch of stories around about disasters caused by them - and I’ve never read a single such story.
heikomat@lemmy.world 10 months ago
If the comments tell you “what” happens, then yes, they can geht outdated fast. The details of how something works can change quickly.
But comments documenting “why” something is done (a certain way) - explaining the intent - are probably valid for mich longer.
In the best case comments aren’t viewed as something that is seperate from the code, but part of it. So that if someone changes the code, the comments has to be checked aswell (if the explanation of “why” something is done actually changed).
astraeus@programming.dev 10 months ago
We shouldn’t waste time documenting our code when we need so much of that time breaking our code
magic_lobster_party@kbin.social 10 months ago
I’ve seen code that look like this:
int delay = 15 * 60; // 10 minutesEven if the comment was on the same line someone forgot to update it.
Better solution is to write (in C#):
TimeSpan delay = TimeSpan.FromMinutes(15)Much more obvious what the code actually means.
18107@aussie.zone 10 months ago
A better comment would be
delay in secondsas that is the one thing not obvious from glancing at the code.magic_lobster_party@kbin.social 10 months ago
Or just name the variable
delaySecondsif you really want to store it as an int. Bonus is that every use of the variable perfectly communicates what it is.CCatMan@lemmy.one 10 months ago
Is the better way is a runtime performance hit. Does the compiler optimize this?
magic_lobster_party@kbin.social 10 months ago
It’s probably a little bit slower, but there are other things more worth to optimize than to shave off a few microseconds from a 15 minute delay.
Awkwardparticle@programming.dev 10 months ago
One day you will inherit a code base so bad that you’ll end up commenting old code just to make sense of it for yourself because nobody in the company has touched in a couple years and the last people that did no longer work there. It will be dangerously coupled, if you make the right change somewhere it will break everything else. It will be true spaghetti code where you spend 30 min just following a code path to figure out what and why an input into a function needs to be what it is to able to come out of another function in an exact format for anything to work.
Your so called comment standards and principals are fine if you are building something from the ground up, but the other 95% of the time, you do what you gotta do because your were blessed with a turd that is impossible to polish.
philm@programming.dev 10 months ago
Will not be the case, I won’t take a job, where I have this situation (or I’ll quit pretty quickly)…
Yeah my “comment standards” (btw. as others mentioned here, I was unprecise/unlucky with the choice of words, I meant “comment the why” or doc-comments totally fine and should be aimed)
Yes that was also targeted with my comment. But what you’re referring to is just missing documentation, and I think this should be done on a higher level. The “comment why” rule applies for spaghetti code non-the-less…
Vilian@lemmy.ca 10 months ago
and if you need an unnecessarily complex ode for performance sake?
hstde@feddit.de 10 months ago
There’s a comment for you to explain the why.
Rule of thumb: code explains the how and what, comments explain the why.
philm@programming.dev 10 months ago
Yeah that’s a good summary
magic_lobster_party@kbin.social 10 months ago
Those cases are rare. Often the most basic solution is good enough.
If you have to write complex code, then you should write a comment (write the name of the algorithm for example).
Test_Tickles@lemmynsfw.com 10 months ago
Rare?
Where do you guys work that all you do is write basic AI generatable code?
The only thing I can think is that you are a bunch of freelance devs who never have to maintain anything or add functionality to old code. Either that or you are all new and are just full of theoretical bullshit that you read on the internet.
CowsLookLikeMaps@sh.itjust.works 10 months ago
Or you’re stuck within the confines of a horrible legacy system which the business will not allow you the time to refactor/rewrite but still want your code to be somewhat readable.
But in general, I agree with your argument. When writing from scratch or improving reasonably well designed code, often documentation could be replaced by breaking it up into another function or naming variable better. It’s a bit of a code smell for violating the SRP.