Comment from my group project teammate. You don't need to comment every line lol
me in a group project ending up doing all the work
this post was submitted on 10 Jun 2024
281 points (94.9% liked)
Programmer Humor
19187 readers
1133 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 1 year ago
MODERATORS
It's much worse to learn development while being lazy about commenting. Or adding them all just before sending your source code to the teacher.
Lol that's exactly what this was. I wrote this python script, and he went through and added comments like this a day before the deadline.
Not trying to throw shade on him though, it's more the university's fault for not explaining what makes a useful comment. I just thought it was funny
} // End of if
CMake does that…
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
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.
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.
#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!
sometimes it's just nice to remember a human wrote a thing
Let the code explain the „how“, use comments to explain the „why“.
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.
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.
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.
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.
I'd rather have no comments than wrong comments.
I’ve seen cases of outdated comments in the same line of code it’s describing. People suck at maintaining 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
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!
view more: next ›