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!
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.
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.
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.
} // End of ifThis brings back trauma
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.
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.
There is usually no such thing as too many comments. There is a point to keep them to the point though
Who upvotes these terrible takes???
Give this comment a read: https://midwest.social/comment/10319821
Well on Reddit, programmerhumor was mostly populated by people weirdly proud of how bad they are at their job, so I don’t see how Lemmy was going to be different.
I mean, it’s better to have to many comments than not enough
Universities often teach students to write a lot of comments, because you are required to learn and demonstrate your ability to translate between code and natural language. But this is one of the things that are different in professional environments.
Every comment is a line to maintain in addition to the code it describes. And comments like this provide very little (if any) extra information that is not already available from reading the code. It is not uncommon for someone to alter the code that the comment is supposed to describe without changing the comment, resulting in comments that lie about what the code does, forcing you to read the code anyway.
It’s like if you were bilingual, you don’t write every sentence in both languages, because that is twice as much text to maintain (and read).
The exception of course, being if you are actually adding information that is not available in the code itself, such as why you did something a particular way.
It’s better to have useful comments. Long odds are that somebody who writes comments like this absolutely isn’t writing useful comments as well - in fact, I’m pretty sure I’ve never seen it happen. Comments like this increase cognitive overhead when reading code. Sure, I’d be happy to accept ten BS useless comments in exchange for also getting one good one, but that’s not the tradeoff in reality - it’s always six hundred garbage lines of comment in exchange for nothing at all. This kind of commenting usually isn’t the dev’s fault, though - somebody has told a junior dev that they need to comment thoroughly, without any real guidelines, and they’re just trying not to get fired or whatever.
Legit, I’ll take this over the undocumented spaghetti I too often see written by “professionals”.
This is so wrong. I would absolutely prefer no comments over incorrect comments, which is exactly what happens when things get over commented
