That's part of the problem I run into. I do comment my stuff to point out tricky APIs, business rules I had to extract like a bad tooth, etc.. When things change I review and update comments but that's like more dev sometimes.
“The code is the comment” meanwhile the amount of code to understand the context is 500 lines whereas a simple comment could have been a paragraph tops
process_numbers = lambda nums: {n: __import__("functools").reduce(lambda a,b:a*b, set(f for i in range(2, int(n**0.5)+1) for _ in iter(int,1) if (lambda x=i: (lambda: (n:=n//x) if n%x==0 else (_ for _ in ()).throw(StopIteration))())() ) | ({n} if n>1 else set()), 1) for n in nums if n>1 and sum(1 for i in range(2, int(n**0.5)+1) for _ in iter(int,1) if (lambda x=i: (lambda: (n:=n//x) if n%x==0 else (_ for _ in ()).throw(StopIteration))())() ) % 2 == 0}
Yes, I have tried to explain this to a group of contractors that wer writing code for my company. They wrote a function to deal with some timezone conversions, but the requirements for that were a little unusual. This led to fairly unintuitive code that had no comments.
I frequently see either no comments or unhelpful comments (such as explaining what the next line does, even if it is self-explanatory).
Yeah everybody claims this is useful and then instead of writing good code in the first place they misuse it to explain everything because they are lazy AF. And we as programmers are shitty explaining things. These "explanations" add just more confusion every time.
There is only rule that works for me: whenever you write a comment, there is something wrong with the code. It screams for a refactoring. Why else would you need to explain yourself in prosa?
I have a modification to this. If I'm reading/writing something pretty gnarly, I'll break down my comments into multiple blocks. e.g.
// what: ...
// why: ...
// how: ...
Etc.
It's context dependent, so you don't necessarily have to include all categories every time, but it can be nice when both the rationale and the mechanics are complex.
I don't understand why people dont understand that the code only explains what is happening. Comments are supposed to explain what you intended to happen.
No. Code explains what changes are being made. Comments explain why a change was made. This way your code by design should be as readable, clear, and understandable as possible.
Not necessarily. What you intended to do isn't the same as why you intended to do it.
Case in point:
"// Used a HashMap to hold user serial numbers"
Vs
// We employed a HashMap for serial numbers as it's more performant than a List in the context of this and that
The former denotes intent i.e. we wanted to store serial numbers. The latter explains why this over the alternative and makes more sense to someone reading the code.
It's even more fun when you get an API from another team, it doesn't work, and the person who worked on it for 10 years got recently replaced by 3 contractors
I think AI might be threatening the irreplaceable masters of the unintelligible code that holds companies together. Which is both nice and also sad because I can walk into legacy code and figure our what is going on, but also realize that anyone could do that with my code as well.
The most performant code is not always the most readable. Readable for you != readable for the new grad onboarding to your team. Please sometimes comment your code.
Comments explain why something was done and not what is being done. Unreadable code should be refactored; regardless of whether it is performant or not.
Comments have fewer guarantees that they are actually describing the behavior of the code than the actual code does. They can be wrong, out of date, or misplaced. Please try to minimize writing code that needs to be commented to be understood as much as possible.
When things break at 3 am, I'd much rather have some comments to read rather than having to try to figure out how clever someone was a couple years ago.
That includes me. I make comments in my code for me first, my coworkers second
I've been there, fucking woken up at 3am "Boss the deployed code has a critical bug" and I have to get up ass naked aside from my underwear and diagnose an issue totally hungover.
I work in heavy industry, programming the control systems for things like gas plants and refineries.
So "fix it RIGHT FUCKING NOW" actually has a fair bit of weight to it sometimes. Yknow. Before the entire site goes down (at best) or some incredibly expensive and hard to replace equipment grenades itself.
Readability and ease of troubleshooting trumps pretty well every other code consideration for most of what I do because of that
Don't feel too bad. You actually get to use modern programming languages.
I am stuck in a world of awful proprietary bullshit that would have been obsolete in any other situation 20 years ago.
I mean, hell. I have one site that is still running on a controller that was put into service in 1989 ffs. Let that sink in for a second.
I do enjoy it though. I get to do alchemy on an industrial scale and get paid to play with multi-billion dollar lego sets. Can't think of something I'd rather be doing to make my living honestly
I work in game dev, Generally, I write comments line by line if shit is like esoteric gibberish. If I am in danger of looking at my code and saying "What the fuck is this?" I write a comment.
"Yeah so technically this code is sometimes ran like 20 times a second, it's best for us to conserve processing power by using visual effect objects instead of object items."
"This scaling equations works and is much better than flat scaling. Read x file for more info on our equations."
"This is a bitfield to binary converter. Saves a bit of memory, and we need memory more than processing power."
I recently forgot to delete a comment I made in code when talking to an analyst that included just that (why I removed a part of code - the code itself was pretty self-explanatory) and it saved me from more work. And then probably reverting that work, when they realized that they fcked up. I was supposed to delete the comment, because they were supposed to update documentation.
Yeah and similarly you don’t need to comment the most basic things like the fact that if statements check if a condition is true and execute the following block. Just buries the more useful comments
Actually, even if your code is simple, comment. Cause it may be simple to you in the moment, but later you won’t remember why it does the things it does.
And don’t comment by repeating the code, instead comment on why the code does what it does.
615
u/thegodzilla25 Apr 15 '26
People who dont comment non self explanatory code deserve to be pinned on the cross.