this post was submitted on 02 Oct 2023
1544 points (98.4% liked)

Programmer Humor

32442 readers
842 users here now

Post funny things about programming here! (Or just rant about your favourite programming language.)

Rules:

founded 5 years ago
MODERATORS
 
top 50 comments
sorted by: hot top controversial new old
[–] [email protected] 84 points 1 year ago (12 children)

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.

[–] [email protected] 55 points 1 year ago (5 children)

Yeah, good code should explain the "what" without the need for comments. Good comments explain the "why".

[–] [email protected] 16 points 1 year ago (1 children)

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)
[–] [email protected] 10 points 1 year ago

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)
[–] [email protected] 46 points 1 year ago (4 children)

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".

[–] [email protected] 35 points 1 year ago (3 children)

"thingyOne" is self explanatory, it's a thingy.

[–] [email protected] 10 points 1 year ago (3 children)

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)
[–] [email protected] 9 points 1 year ago (3 children)

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)
[–] [email protected] 23 points 1 year ago (5 children)

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.

[–] [email protected] 20 points 1 year ago

The build approval process actually stripped out all comments via a script.

Thanks, Satan.

[–] [email protected] 11 points 1 year ago

I'd watch the movie.

load more comments (3 replies)
[–] [email protected] 7 points 1 year ago

It kind of feels like engineers look for simple solutions to what are ultimately complicated psychological questions sometimes.

load more comments (8 replies)
[–] [email protected] 62 points 1 year ago (7 children)

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.

[–] [email protected] 39 points 1 year ago (1 children)

The vitriol the "Clean Code" cult has against comments is unbelievable...

load more comments (1 replies)
[–] [email protected] 25 points 1 year ago* (last edited 1 year ago) (2 children)

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

[–] [email protected] 14 points 1 year ago* (last edited 1 year ago) (1 children)

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.

[–] [email protected] 10 points 1 year ago* (last edited 1 year ago) (1 children)

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)
[–] [email protected] 7 points 1 year ago

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

[–] hoodle 13 points 1 year ago

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)
[–] [email protected] 58 points 1 year ago (4 children)

My favorite part is looking at my ancient code and thinking "Holy hell I don't remember being that smart. What happened?"

[–] [email protected] 31 points 1 year ago

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

[–] [email protected] 11 points 1 year ago

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...

[–] [email protected] 8 points 1 year ago

"I'm dumber but wiser" - me, hopefully

load more comments (1 replies)
[–] gens 49 points 1 year ago (2 children)

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.

[–] [email protected] 17 points 1 year ago (2 children)

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)
[–] [email protected] 28 points 1 year ago

When the the documentation is epic, but no one remembers to add why this repo even exists.

[–] [email protected] 22 points 1 year ago (1 children)

I think the images are inverted

load more comments (1 replies)
[–] [email protected] 19 points 1 year ago (1 children)

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)
[–] RandomVideos 17 points 1 year ago (4 children)

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)
[–] [email protected] 16 points 1 year ago* (last edited 1 year ago)

`/* 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()) }`

[–] [email protected] 16 points 1 year ago

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"

[–] [email protected] 11 points 1 year ago

Of course we forget how it works.

The whole point of the documentation is to help remembering.

[–] [email protected] 11 points 1 year ago

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

[–] [email protected] 7 points 1 year ago* (last edited 1 year ago) (3 children)

Let copilot do it. Junior developers can now efficiently write useless comments like the rest of us

load more comments (3 replies)
load more comments
view more: next ›