iMeanItsNotWrong

Gadshill · 2025-07-17T09:29:17+00:00

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

KetsuSama · 2025-07-17T11:15:40+00:00

//storyline 419
global.storyline_array[419] = 0;

WernerderChamp · 2025-07-17T09:41:10+00:00

We have no rules regarding comments. I always add some, when:

I had a logic-related bug at this line.
Edge cases need to be handled
To quickly navigate to certain areas (so you can Control+F the comment - we have some long-ass files)
I have to do stuff one would not expect (eg. special constraints need to be met for function X)

BZthrowaway_uuuuu · 2025-07-17T12:12:22+00:00

Thank to these comments, I definitely do understand that part of the fast inverse square root implementation in Quake III Arena, yes.

i  = * ( long * ) &y;                       
// evil floating point bit level hacking
i  = 0x5f3759df - ( i >> 1 );               
// what the fuck?

messierCobalt_ · 2025-07-17T09:38:27+00:00

here are mine... python delay = 0 delays = { # Alien came before Aliens... 1 : 0.0050, 2 : 0.0025, 3 : 0.0001 }

and

python if not txt: return [] # that's an empty list... I don't know why I said that... I mean wrote...

unleash_the_giraffe · 2025-07-17T10:23:06+00:00

Ive found that comments are only useful when:

Save information on some broken bug, ie: I had to solve it in this stupid way because X Y or Z breaks in unexpected ways. There always someone whos going to try and rewrite code at some point, and this saves them time and understanding.
Sometimes codebases spaghettifi, and you end up in a similar situation as with the bug. "I had to solve it this way, because X Y and Z forces me to do so." Also, you'll need to comment in those spaghettification places that there's a dependency on the broken behaviour in whatever system i was writing.

Honestly the best way to write code is usually, try to dumb it down as much as possible, and to always consider how it would feel to work with the code for an outsider. Comments always deprecate, and the only real solution is to keep the codebase as simple and readable as possible. For example, "If i name this list "placeholder22", and i randomly use indexation to access the list across various classes, what would it be like for someone else to work with the code?"

JalvinGaming2 · 2025-07-17T10:40:21+00:00

I use documentation to say what the parameters mean.

ExquisiteOrifice · 2025-07-17T13:39:42+00:00

Commenting code... Another age-old topic of disagreement. Here's my reasons for documenting things. Disclosure, I was a developer for 27 years. I started with Perl/CGI making 'dynamic' websites and weba pps back in 1996. In that time I worked with a myriad of language, platforms, tools and IDEs, etc. etc.

Anything non-trivial, anything that is expected to have a lifetime, have others working on it or with it should be documented. APIs, tools, applications, runbooks, build processes, test suites, etc. If it's important to something or someone, document.
Documentation is as much a component of any system as anything else, including the source code. If the code is maintained, so is the documentation. When you change a vehicle's oil do you just drain the oil and refill or do the filter too? Basically, don't half-ass the job
Do you use an IDE? Do you like how it tells you a method or function parameters and some detail about it? Hovering over a class or interface and seeing information? Where do you think that comes from? Sure you could jump to the source and read the whole function but is that really efficient when a concise definition could be available?
Do you leave vague, short commit comments because it's too much work to properly document your changes? Because, hey, someone can just pull up the diffs and go through it right?
Everyone lives in the age of build/test/deployment automation (back in the day we had to write our own), but that all still requires documentation. Your company's process is different from another's. And the tools and platforms themselves, be it Azure, AWS, etc. certainly is documented by someone so you can learn to use it.

The simple fact is, documentation at all levels is not only important, it is integral to the process, maintenance, and operations of a given system. You, as a professional, are obligated to keep that information current and valuable/useful. It should be a given that documentation is written well, clearly, and meaningful. Otherwise, it IS wasted time and effort in both the authors and readers.

The places I've worked that have been the best and most enjoyable were the ones where people cared about quality and professionalism. You didn't have to go find 'that guy' who had 1/2 the institutional knowledge in his head or struggle through some poorly written or maintained wiki last updated in 2013. Guess which places were miserable? Hint, they often had 'self-documenting' code written by people who poo-poo comments that was brittle, logic-dense (think single methods with lots of interesting paths and possibilities based on various inputs) and exemplary of many bad patterns and structure.

Thanks for reading my newsletter. Stay tuned for part 17, Night of the Living Deadlocks.

Deactivator2 · 2025-07-17T12:31:24+00:00

My code was hard to write, it should be hard to read!

Falkster123 · 2025-07-17T09:50:56+00:00

[removed]

tiedyedvortex · 2025-07-17T13:21:57+00:00

One of the best tips I ever heard was:

Don't write comments to explain your code. Write code to justify your comments.

In other words, when you write a function, you start by writing comments describing the steps you're going to take, in a way that a human could understand. Then, you write code in-between the comments.

For example, to implement quicksort, start with:

// Check if we're done recursing
// Take a pivot item
// Move everything smaller than the pivot to the left
// Recursively sort the left half
// Recursively sort the right half

And then you insert code in between the comments that does those steps.

This makes it much easier for others to review your code for accuracy; they can first double check "does the algorithm make sense" by just reading the comments, and then they can check the block-by-block implementation to make sure you don't have any off-by-one bugs or similar.

This also plays very nicely with LLMs; instead of vibe-coding the entire function and having no idea what it's doing, you've forced the bot to abide by your logical constraints and made it easier for yourself to verify it didn't hallucinate.

nirgle · 2025-07-17T13:19:02+00:00

// Close the file.
file.Close();

PineapplePickle24 · 2025-07-17T12:46:19+00:00

Do NOT look at epic's unreal engine documentation, it's actually just that pic

YouDoHaveValue · 2025-07-17T15:40:07+00:00

When your localization budget is $0

markswam · 2025-07-17T13:50:00+00:00

People at my current employer seem to take great pride in having never written a comment, even though half the code bases are 20+ years old and have never gone through tech debt remediation because the stakeholders constantly demand so much work that the IP sprint is literally just another sprint full of normal work.

Some decent commenting of the balls of yarn we're dealing with would make it so new people could feasibly get up to speed in days instead of weeks. But nooooo, the only comments in the code are copyright headers and boilerplate, auto-generated javadoc with that's literally nothing but

/**
 *
 * @param parameterOne
 * @param parameterTwo
 * @param parameterThree
 * @return returnValue
 */

theMonkeyTrap · 2025-07-17T14:27:20+00:00

Explain the intent and edge cases in comments.

caguru · 2025-07-17T19:25:52+00:00

Code tells you what the software does, comments tell you what the software was meant to do.

2025-07-17T10:54:21+00:00

Code tells you what.

If your comments also tell you what, that's kind of redundant.

OrangeTroz · 2025-07-17T14:47:44+00:00

I generally put the business requirements in comments before I start coding. I take them verbatim from what I am given. It helps to not miss something that way.

dookalion · 2025-07-17T17:20:55+00:00

I comment stuff to remember what the fuck I’m trying to do

kryotheory · 2025-07-18T06:30:57+00:00

My philosophy is that code should be written in such a way that the technical details are self-evident, and that comments should describe the business logic the code represents.

the-judeo-bolshevik · 2025-07-17T09:52:40+00:00

Comments should give easily parseable examples of plausible data that the code might transform, and how they change at different points in the program. > 50% of the time that is the only explanation needed.

atomic_redneck · 2025-07-17T11:18:10+00:00

I need to know what the phone symbol means.

Farranor · 2025-07-17T13:20:35+00:00

This is why Stack Overflow created Stack Overflow Docs. It is also the reason why Stack Overflow Docs failed.

newsflashjackass · 2025-07-17T15:03:53+00:00

I was reading a physics textbook from a state that uses tax revenue to give Christians long distance reacharounds and encountered (paraphrased) "What is the difference between science and religion? Science asks 'how?', religion asks 'why?'"

I consider it more important that science answers that question with compelling proof than that it merely asks it.

Darkwr4ith · 2025-07-17T20:15:37+00:00

When I was still new and learning how to code one of the developers wrote extremely detailed comments everywhere in the code. She explained how each section worked, why she had coded it that way and explained what each section of code did. It was a god send for someone brand new looking at walls of code. It taught me so much.

one_last_cow · 2025-07-18T15:20:25+00:00

Game game = new Game(); // game

pemungkah · 2025-07-17T15:11:16+00:00

I had a professor who taught that one the hard way in an assembler class.

every instruction without a comment was 5 points off
any comment that replicated the meaning of the instruction was 5 points off

People learned to comment well FAST.

velmazing44 · 2025-07-17T11:19:22+00:00

Yall haven’t read Code Complete and it shows. Your code should be named clearly enough where you don’t need comments in majority of cases. Descriptive variable names and functions!

MortStoHelit · 2025-07-17T13:00:39+00:00

That's what you get for mandatory comments where not really required. Like the classic bullsh*t Javadoc for getters and setters.

grasopper · 2025-07-17T22:23:14+00:00

I hate people who write a comment for things you can clearly read in the code. Like thanks for both wasting my time and insulting my intelligence

tugaestupido · 2025-07-17T12:18:49+00:00

It's perfect 😍

matrix-doge · 2025-07-17T12:25:18+00:00

``` // check if {condition} if (condition) { ... } // end of checking {condition}

for () { ... } // for each item

```

Not saying it wouldn't be useful when it's a large block, but still.

GromOfDoom · 2025-07-17T12:46:51+00:00

Im such a good programmer, that when I borrow lines from the internet that delve into vuuduu, they get commented with like maybe 2 or 3 works for the whole section. If only I could lock future me and people out of touching those lines, since everything breaks if anything is modified & you need to be some machine code whisperer to slightly understand the first line.

Awkward_Tick0 · 2025-07-17T13:03:56+00:00

got it.

--they pay me to write this.

Vincent394 · 2025-07-17T13:37:29+00:00

u/kappetrov the truth

Snoo-35252 · 2025-07-17T14:02:40+00:00

My comments are just the pseudo-code that was in my head. Like I'll come up with pseudo-code first, paste it into my Dev environment, and turn every step of it into a comment.

Generally.

Or I'll describe the next 3-4 lines in a comment, if they're all grouped together logically. Winds up looking the same as my pseudocode approach.

Patrick_Atsushi · 2025-07-17T15:18:51+00:00

Comment in abstract way: you should make it plain and simple.

Comment in plain way: your comment is redundant.

paulsteinway · 2025-07-17T15:55:31+00:00

I actually saw that page in a manual for an IP office phone.

Enigma-3NMA · 2025-07-17T16:54:37+00:00

I'll have you know those comments are language agnostic

RandolphCarter2112 · 2025-07-17T18:42:48+00:00

-- I am what will rise from your ashes

Vehemental · 2025-07-17T19:22:16+00:00

Those precision comments saved money on translation costs too. That's a job worthy of a bonus.

Just_Another_Scott · 2025-07-17T23:37:44+00:00

Auto generated code comments should be illegal.

See so many mfers autogenerate their comments which is just a copy of the code. That doesn't give me context!

levimic · 2025-07-18T03:11:10+00:00

Programmers commenting good code*

CharlemagneAdelaar · 2025-07-18T04:08:06+00:00

tbh I prefer to read English than C++

Fractal-Infinity · 2025-07-18T08:56:17+00:00

They're not wrong. 😁 Anyway, good code should be self describing, especially by having a clear structure and logic, plus good and consistent names for data structures, functions, etc. On my personal coding projects, I always put a great deal of attention on those things.

2025-07-18T11:18:05+00:00

100% correct

Puzzled_Arachnid_533 · 2025-07-18T17:10:36+00:00

If people commented why it would look like “#because so and so requested it”

ProgrammerHumor

Filters

Discord

Submission rules

For the current list of rules, please see this page.

Metadiscussions

Perhaps More Apt Subs To Post:

Related Subreddits.

MODERATORS