this post was submitted on 02 Oct 2023
1544 points (98.4% liked)
Programmer Humor
32724 readers
67 users here now
Post funny things about programming here! (Or just rant about your favourite programming language.)
Rules:
- Posts must be relevant to programming, programmers, or computer science.
- No NSFW content.
- Jokes must be in good taste. No hate speech, bigotry, etc.
founded 5 years ago
MODERATORS
I had so many arguments with my team lead. He thought comments were an antipattern because that meant the code wasn't expressive enough.
I understood where he was coming from, but a little hint here and there why the fuck the code is doing what it's doing would've been nice.
Yeah, good code should explain the "what" without the need for comments. Good comments explain the "why".
Generally, you can replace some comments with variable names or comment names. Which means you must already be in the habbit of extracting methods, setting new variables to use appropriate names, and limit context to reduce the name (Smaller classes and methods means shorter names can be just as expressive, because the context is clearer). It lowers the number of wtfs per minute you get reading code before you even need whole sentences to explain why things are done in a certain way, because the names can be a powerful hint.
But realistically, you end up needing comments for some things anyways.
load more comments
(1 replies)
Also some parts of code are just going to smell, because of deadlines, other trade offs. For those it helps to have a comment to really highlight that bit of weirdness - the what and the why. If it is weird it should really "pop out" when you're reading it.
load more comments
(3 replies)
I used to work with a guy who insisted his code was self explanatory, and then he'd nest loops 5 levels deep and give variables names like "thingyOne".
"thingyOne" is self explanatory, it's a thingy.
Namely, the first one. Next you're going to ask about thingySixtyNine or thingyOneHundredTwentyTwo, I suppose?
load more comments
(3 replies)
load more comments
(2 replies)
That guy wasn't in charge, I hope? That would not have passed code review with me at least.
load more comments
(3 replies)
load more comments
(2 replies)
I had a boss who hated comments because he wanted "clean code," and that comments means you aren't using the wiki. The build approval process actually stripped out all comments via a script.
Then we lost the wiki.
The build approval process actually stripped out all comments via a script.
Thanks, Satan.
I'd watch the movie.
load more comments
(3 replies)
It kind of feels like engineers look for simple solutions to what are ultimately complicated psychological questions sometimes.
load more comments
(8 replies)
I am working with an in-house "rapid development team." They have rigorous intake, story and task break down, scheduling of sprints, QA, definition of done, integration test coverage, E2E and min 90% unit test coverage etc. etc.
They have a strict policy of "no code comments, self documenting code only." They will go in and remove comments that my DevOps team puts in there, because it screws up that policy.
Luckily, we adopted the policy of having local branches with these comments in place. Once they move beyond the project, we're putting them in.
The vitriol the "Clean Code" cult has against comments is unbelievable...
load more comments
(1 replies)
They do have a point though. When we’ve gone through phases where the industry focuses on commenting code and other documentation, most of it is useless.
Code comments should have a reason, and are no substitute for readable code.
However you’re also right though that people jump onto “all or nothing”. I recently did a code Review that I held up for comments. In this case, they were doing something very atypical to get around a limitation so it was a clear case of comments needed. The next person through will say “what is this shit?” And “fix” it, without knowing there was a good reason
Yeah "why" comments are absolutely fine, "what" comments are useless at best and can be harmful at worst.
I feel like this constant flood of "write comments" posts are from CS students who are told to comment everything by their lecturers. Descriptive variable and function names help explain the "what" of code pretty well most of the time.
Sure with some old languages like C89 where you are limited in your variable name length you probably do need comments to explain wtf is going on, but most code bases aren't as constrained.
I have this argument with other devs all the time.
Hey, you know this 200 line nested if statement that suddenly returns in the middle of the condition is "7"? Yeah, that needs a refactor or at least a fucking comment.
I get a pull request that adds a log line that reads something like "special case 7 triggered.".
load more comments
(1 replies)
Having no comments doesn't force code to be self-documenting. I understand the cult of code extremist, but No-Commenters are just WEAK and PATHETIC wannabes trying to immitate the true, functional extremists, such as the 16-Space-Tabbers
That's silly. I've never seen comments even as a way to explain what your code is doing (the code often does do that anyway). It's important to say WHY you're doing it the way you are.
That way anyone else who comes in there can have the same context you did when you implemented it, which imo is where most bugs occur. People don't realize what assumptions you made when it was first written, and then make their own (which can easily clash).
load more comments
(4 replies)
My favorite part is looking at my ancient code and thinking "Holy hell I don't remember being that smart. What happened?"
Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?
Brian Kernighan - The Elements of Programming Style, 2nd edition, chapter 2
A similar phenomenon is knowing you're going to need to go back and update some older section of code and when you finally get around to it, it turns out you wrote it that way to begin with. It's like... I didn't think I knew about this approach before...
"I'm dumber but wiser" - me, hopefully
load more comments
(1 replies)
I'd like all files to have a big comment on top that says wtf this is, why is it, and roughly how it works. Bonus for ascii art.
My favorite is the 'here be dragons' ASCII art, that's how you know you're in for a fun time
load more comments
(2 replies)
load more comments
(1 replies)
When the the documentation is epic, but no one remembers to add why this repo even exists.
The obvious solution is to abandon your project not too late; leave on a high note.
I also found it very useful to document every step of my setup procedures, right after I figured out what works. At least the respective CL.
load more comments
(1 replies)
I have a special skill of writing terrible code, not seeing it for half a year, and then remembering exactly what the code did
load more comments
(4 replies)
`/* Gets CustomerEntity from customer repository by customer ID or throws a customer not found exception */
public CustomerEntity getCustomerEntityById(String customerId){ customerRepository.findById(customerId).orElseThrow(new CustomerNotFoundException()) }`
I've had a legit conversation where I just plain said "I copied the component as it was. I would ask the original developer why the thing was implemented that way, but sadly he no longer works here"
Of course we forget how it works.
The whole point of the documentation is to help remembering.
An awful lot of people in here talking about automatic comment removal and I ... don't believe it. I think a lot of you are making up stories. Show me proof that a build script removed your comments, because it's not just bad policy, it's literally insane. Nobody would do that. Anyone that thought of doing that would spot the folly of doing it within 5 minutes, and immediately stop. GTFO
Let copilot do it. Junior developers can now efficiently write useless comments like the rest of us
load more comments
(3 replies)
view more: next ›