Writing good comments is an art form, and beginner programmers often struggle with it. They know comments mostly from their text books, where the comments explain what is happening to someone who doesn’t yet know programming, and nobody has told them yet that that is not at all a useful commenting style outside of education. So that’s how they use them. It usually ends up making the code harder to read, not easier.
Later on, programmers will need to learn a few rules about comments, like:
Assume that whoever reads your code knows the programming language, the platform and the problem domain at least in general terms. You are not writing a teaching aid, you are writing presumably useful software.
Don’t comment the obvious. (Aside from documentation comments for function/method/class signatures)
Don’t comment what a line is doing. Instead, write your code, especially names for variables, constants, classes, functions, methods and so on, so that they produce talking code that needs no comments. Reserve the “what” style comments for where that just isn’t possible.
Do comment the why. Tell the reader about your intentions and about big-picture issues. If an if-statement is hard to parse, write a corresponding if clause in plain English on top of it.
In some cases, comment the “why not”, to keep maintenance programmers from falling in the same trap you already found.
I would argue that if an if statement is hard to parse, replace the entire condition with simpler to read (but way more specific) variables that you assign values (the original condition expression) in the line above. No need for comments in that case
Don’t comment what a line is doing. Instead, write your code, especially names for variables, constants, classes, functions, methods and so on, so that they produce talking code that needs no comments.
Over and over and over again in my experience this just doesn’t work. Readable code does not substitute for comments about what the code should be doing.
In this day and age of source control I don’t think this is fully necessary. If you want to know the why, you can look into the commit history and see which ticket is connected to it. There you might even see the discussions around the ticket as well. But this requires good source control discipline.
Why not put the “why” in a comment and save people the job of dredging through old commits and tickets to figure out what the code is for? I’d thank someone for saving me the hassle.
In any modern IDE “dredging through old commits” means clicking a single button to see who last changed the line. From there it often makes sense to go look at the PR to see a higher level of what was changed. You cannot include all of that context in a single comment.
Going back to the original ticket can offer far more info than what any “why” comment can give. You can see how old it is, if there are any connected tickets, who were involved with it, step by step instructions how to reproduce the bug, etc.
Writing good comments is an art form, and beginner programmers often struggle with it. They know comments mostly from their text books, where the comments explain what is happening to someone who doesn’t yet know programming, and nobody has told them yet that that is not at all a useful commenting style outside of education. So that’s how they use them. It usually ends up making the code harder to read, not easier.
Later on, programmers will need to learn a few rules about comments, like:
Commenting the why not is key. Half my comments are explaining why I had to use this hack as a warning that the obvious fix doesn’t work!
I would argue that if an if statement is hard to parse, replace the entire condition with simpler to read (but way more specific) variables that you assign values (the original condition expression) in the line above. No need for comments in that case
Over and over and over again in my experience this just doesn’t work. Readable code does not substitute for comments about what the code should be doing.
In this day and age of source control I don’t think this is fully necessary. If you want to know the why, you can look into the commit history and see which ticket is connected to it. There you might even see the discussions around the ticket as well. But this requires good source control discipline.
It has helped me many times.
Why not put the “why” in a comment and save people the job of dredging through old commits and tickets to figure out what the code is for? I’d thank someone for saving me the hassle.
In any modern IDE “dredging through old commits” means clicking a single button to see who last changed the line. From there it often makes sense to go look at the PR to see a higher level of what was changed. You cannot include all of that context in a single comment.
You can also do that if you think it’s useful.
Going back to the original ticket can offer far more info than what any “why” comment can give. You can see how old it is, if there are any connected tickets, who were involved with it, step by step instructions how to reproduce the bug, etc.