Comment from my group project teammate. You don’t need to comment every line lol
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.
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
Good advice, just to add to this:
- Comments should be part of code review, having at least two pairs of eyes on comments is crucial. Something that’s obvious to one person maybe isn’t so obvious to another. Writing good comments is as hard or harder than writing good code, so having it checked for mistakes and quality is a must
- Comments aren’t the actual documentation and aren’t a reason not to write documentation to go along with your code. Often I see larger projects where each class and function is documented in comments, but the big picture and the how and why of the overall structure is completely missing. Remember that in the real world you often have a lot of folk that need to understand how the code works, who aren’t programmers themselves. They can’t read the code or don’t have access to the code. Writing documentation is still important.
- Please for the love of god when you change code, check if the comments need to be updated as well. Not just around the immediate area, but also the entire file/class and related files. I’ve worked on large codebases before with a high wtf factor and having the code do something different to or even opposite the comments is a nightmare. I’d rather have no comments than wrong comments.
This is a notoriously bad book. If you read the part about comments (which I don’t know about, and am willing to accept is good) make sure to skip everything else because Robert Martin is a fraud.
Agreed, removed
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.
Do comment the why
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.
Software devs in general seem to have a hard time with balance. No comments or too many comments. Not enough abstraction or too much, overly rigid or loose coding standards, overoptimizing or underoptimizing. To be fair it is difficult to get there.
It’s an art, not a science. Which is where I think a lot of people misunderstand software development.
} // End of if
This brings back trauma
okay but which ‘if’ is ending ??
The outer most. (There were 4 layers of nested ifs.)
too few. i like to have a nice big gap on the left of the code so theres a place to write notes when i screenshot the code
CMake does that…
More useful would be what sort of values is acceptable there. Can I use team number 2318008? Can I use team 0? If not, why not? WHY / WHY NOT is often useful.
I am not a programmer, I just barely wrote one bash script in the past. But I’d say more comments are better than too few.
When I later wanted to edit it, I got completely lost. I wrote it with absolutely no comments.
Bash is a shit „language” and everytime i need to write the simplest thing in it I forget which variable expansion I should use and how many spaces are the right amount of spaces. It’s impossible to write nice to read bash, but even in C you can write code that comments itself.
It’s perfectly possible to write nice to read bash, and to also make is safe to run and well-behaved on errors.
But all the three people that can do those (I’m not on the group) seem to be busy right now.
Yeah you lost me at well behaved.
Still better than powershell though
bash sucks but i don’t agree. Some simple rules like regularly use intermediate variables with useful names and never use shorthand arguments goes a long way.
Wrong. Too many comments makes the code messy and less readable and also it provides ZERO value. Just look at the post, WHAT is useful about ANY of that comment???
All it is is a waste of goddamn space, literal junk crowding the actual code.
I love how you admit you aren’t a developer but feel quite confident to tell us that a larger number of comments automatically means it’s better.
This person articulated it better than I: https://midwest.social/comment/10319821
Too many is still better than too few, and it’s not close. Useless comments make parsing a bit harder. Missing comments can mean hours of research.
These are arguments talking past each other. Sure 1 useful comment and 9 redundant ones can be better than zero, but comments are not reliable and often get overlooked in code changes and become misleading, sometimes critically misleading. So often the choice is between not enough comments versus many comments that you cannot trust and will sometimes tell you flat-out lies and overall just add to the difficulty of reading the code.
There’s no virtue in the number of comments, high or low. The virtue is in the presence of quality comments. If we try to argue about how many there should be we can talk past each other forever.
I’ve been programming for almost 25 years and I’d still rather see too many comments than too few. A dogmatic obsession with avoiding comments screams “noob” just as much as crummy “add 1 to x” comments. If something is complex or non-obvious I want a note explaining why it’s there and what it’s supposed to do. This can make all the difference when you’re reviewing code that doesn’t actually do what the comment says it should.
While this is true, an alternative is to name your variables and functions descriptively so that when you see
number_of_cats
you know that variable is the number of cats, andbuyAnotherCat()
is a function that increases the number of cats.
Reminds me of every fuckin PR I do for the Indian contractors that were sold to us as “senior devs” but write code like a junior and you better believe every other line has the most obvious fucking comment possible
Better than writing beginner level crap that is at the same time super cryptic and not documenting at all. We have a bunch of that in our codebase and it makes me wonder why these devs are writing extension methods for functionality already built into the standard libraries.
Better than writing beginner level crap that is at the same time super cryptic and not documenting at all. We have a bunch of that in our codebase and it makes me wonder why these devs are writing extension methods for functionality already built into the standard libraries.
Let the code explain the „how“, use comments to explain the „why“.
We all started somewhere
The problem is that many don’t leave the starting line
#tell me what it’s about
print(“tell me about it”)
#team number = 1 team_num = 1
Comments lie to you!
It’s not that bad. It definitely helps in long functions.
I’m an advocate for code commenting itself, but sometimes it’s just better to comment on what you’re doing, and in those cases it helps to over commentate.
Instead of letting the reader interweave code reading and comment reading, I think it’s better to do either. Either you go full self describing code, letting the reader parse it as code,m, or you abstract everything, making it more of an explanation of your reasoning, and abstract lines that may look too complicated.
Not every comment needs to be useful, but I still write them to not have this switch between reasoning and thinking in code. It can also double as rubber duck debugging too!