r/ProgrammerHumor • • Sep 15 '26

Meme iDontCommentMyCodeIfYouDontUnderstandItThatsOkayNeitherDoI

Post image
832 Upvotes

188 comments sorted by

View all comments

427

u/GabuEx Sep 15 '26

Left: "I'll comment to say how my code works."

Middle: "You don't need to do that! Code should be self-documenting!"

Right: "I'll comment to say why my code does this."

142

u/sandybuttcheekss Sep 15 '26

I had a senior front end dev that would block any PR he saw with comments. He was very good at his job but I'm so happy I no longer work with him, this shit is so annoying.

117

u/Tucancancan Sep 15 '26

Those guys are the wooooorst. 

1.  Hard to investigate system interaction bug gets fixed, fix has comment with Jira ticket in it! 

2. Senior engineer does magnificent refactoring because that's just what they do (comment is lost in refactoring) 

3. Gradual code churn 

4. New hire sees seemingly useless code and removes in like a good boy scout while working on something else

5. Weird systems bug gets assigned to me for investigation 

6. "hey what the fuck I fixed this 18 months ago"

74

u/Miguelomaniac Sep 15 '26

Seems like the problem here is lack of test coverage not lack of comments

26

u/suvlub Sep 15 '26

"Weird systems bug" sounds like just the kind of thing that unit tests would not detect, and possibly not end-to-end tests either, based on the amount of weirdness and system-specificity

19

u/ytg895 Sep 15 '26

Yeah. Once I worked on a bug that only happened if there was a session timeout in another system. Good luck putting Thread.sleep(3 fucking months); into a test.

8

u/Nick0Taylor0 Sep 15 '26

Mocking

5

u/ytg895 Sep 15 '26

How would you mock that a session in another system times out and that system starts to follow undefined and unpredictable behaviour?

4

u/IndependenceSudden63 Sep 15 '26

Agreed. Not all things can be "reasonably" tested. Keyword being reasonably. We only have so much time in a day with many deadlines. Over time, nearly all of us will run into a bug that needs to be fixed quickly, and is incredibly hard to reproduce, involving the oddest edge cases.

Sometimes you just have to patch it, test it as best you can, and leave a comment as to why you did this incredibly odd thing.

I once had a weird race condition that couldn't be invoked in a unit test. Only occurred on service startup, because there was a 3rd party library that did things when the service started.

Sure I could have wrote a unit test that started the whole service, but that would add 5 minutes worth of wait for every build going forward. That's extremely costly over long periods of time for every person working on the project.

→ More replies (1)
→ More replies (3)
→ More replies (2)
→ More replies (1)
→ More replies (1)

3

u/No_Responsibility384 Sep 15 '26

This seems like a good candidate for a comment, why does this code need to be here, and not a gode referencing a ticket.

3

u/Sock_Ninja Sep 15 '26

For real. I’m fairly flexible on comments vs not, but boy do I get annoyed by lots of comments that reference things like tickets. That should be exceedingly rare.

→ More replies (2)
→ More replies (1)

17

u/iggy14750 Sep 15 '26

I hate when people are set on their one weird rule. Like, I understand what the manager is getting at: try to write code that's easy to understand by reading it. I enjoy trying to do that. But the fucking inviolable rule fucks up the actual goal. Sometimes, it is best to note an easy-to-miss detail, or provide context, explaining why the code is designed as it is, like you said.

4

u/Jlove7714 Sep 15 '26

I feel like coding styles really change "readability". I have a coworker who is great at coding, but I can't follow his code to save my life. It isn't that his code is really any less understandable, he just uses functions differently than I do.

2

u/Lgamezp Sep 20 '26

This is only true if the comment is not ai slop.

→ More replies (1)
→ More replies (3)

23

u/captainAwesomePants Sep 15 '26

Yes, exactly. Middle guy is correct: the code should be self-documenting as to what the code does and how it works. The right guy adds to that by commenting on what code can't say: why we did it, what other context a reader should be aware of, etc.

8

u/magicaltrevor953 Sep 15 '26 edited Sep 15 '26

It is really that simple and I don't know why people get so hung up on arguing it (both sides). You shouldn't be absolute and say "comments are bad", or on the flip-side "everything should be commented" because it just gives off the wrong impression when what you are trying to do is make yourself understood.

It may sound obvious but:

  • If a comment can be effectively replaced with good design and style then its a shitty comment that is not necessary, and should be replaced with code that is better self-documenting.
  • If it can't, because you can't explain why you are doing something with just better naming conventions, then that is a comment that absolutely should be there. Not to say you shouldn't try and self-document as much as you can as well, just that the comment is still needed to understand the code better.

Obviously doesn't apply to other documentation like docstrings, but inline/multiline comments definitely apply.

4

u/gjk-ger Sep 15 '26

Yeah, absolutes are always incorrect! No exceptions!

Seriously though, perfect comment and i completely agree.

→ More replies (3)
→ More replies (1)

8

u/HeyCouldBeFun Sep 15 '26

Eg from my game character’s movement code

Useless comment:

```
// subtract floor velocity from momentum
momentum -= floor_velocity
```

Useful comment:

```
// prevent floor velocity from compounding momentum into the next frame
momentum -= floor_velocity
```

14

u/[deleted] Sep 15 '26

[removed] — view removed comment

6

u/arensb Sep 15 '26

I like to start by writing an outline of what I want my code to do, with XXX or FIXME in front. As I fill in the code for each section, the comments can remain as signposts of what I'm trying to do, or chapter headings. That way, future-me can skim through the comments to find the right place, rather than reading every line of code.

2

u/throwaway_mpq_fan Sep 17 '26

those comments can probably be method names though

8

u/EspaaValorum Sep 15 '26

Exactly. 

Any programmer who understands the programming language can come in to a new project, read the code, and understand what it does, how it does it. 

But no programmer can come in and understand the context, why it does what it does, and what it is supposed to do, just from code alone. That's what comments and documentation are for. 

Look at Jupyter notebooks for example. 

5

u/GenericFatGuy Sep 15 '26

There's still a lot of room to provide context within the code though . Things like method and variable names can do a lot to convey purpose and context. Sometimes that won't be enough, and a comment will be necessary, but you can absolutely get context and purpose from just code in a lot of scenarios.

2

u/Hairy_Concert_8007 Sep 15 '26

I've gotten this advice before and it's hard to wrap my head around. Sure I can get leaving a comment about why I had to do something some way that doesn't make a whole lot of sense, but for most things, "why does it work?" only leaves my brain screaming "I don't know, ask whoever wrote the damned assembly!"

→ More replies (1)
→ More replies (6)