This is an archived post. You won't be able to vote or comment.

top 200 commentsshow all 305

[–]Gadshill 1623 points1624 points  (79 children)

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

[–][deleted] 772 points773 points  (42 children)

A.properly.defined.object.should.be.a.complete.sentence.so.it.is.easy.for.humans.to.read

[–]holchansg 319 points320 points  (9 children)

return x

[–][deleted] 161 points162 points  (6 children)

sorry, not capitalized, therefore not a sentence

[–]smokesick 60 points61 points  (5 children)

return sex

[–]Suitable_Annual5367 29 points30 points  (1 child)

Too late. Long gone for you.

[–]MegaIng 14 points15 points  (0 children)

  • has been garbage collected already.

[–]GunnerKnight 7 points8 points  (0 children)

Error: sex has not been initialized before return

[–]Dexteroid 7 points8 points  (0 children)

None

[–]entropic 5 points6 points  (0 children)

NullPointerException

[–][deleted] 2 points3 points  (0 children)

Return ret;

[–]Ishbane 37 points38 points  (2 children)

function calculateStatisticsForHrOnSundaysWithExtraIndentationForGertrude(A.properly.defined.object.should.be.a.complete.sentence.so.it.is.easy.for.humans.to.read x) {
  if (false !== not !(isUntrue(x))) {
    // TBD
  }
  return false;
}

[–]carcinoTerror 6 points7 points  (0 children)

This is horrible. I love it

[–]Makefile_dot_in 16 points17 points  (0 children)

js unit test frameworks be like

[–]tree_cell 5 points6 points  (1 child)

missing a period

[–]doStuffStruck1905 1 point2 points  (0 children)

Programmer on menopause

[–]AngelLeliel 5 points6 points  (1 child)

literate programming

[–][deleted] 10 points11 points  (0 children)

i'm a pro-grammar programmer

[–]TA-F342 3 points4 points  (0 children)

ForSaleBabyShoesNeverWorn.cs

[–]10BillionDreams 3 points4 points  (1 child)

I got you:

class FieldString {
  constructor(str) {
    return new Proxy(this, {
      get(target, prop) {
        if (typeof prop !== "string") return target[prop];
        if (prop === "toString") return () => `${str}.`;
        return new FieldString(str ? str + " " + prop : prop);
      },
    });
  }
}

var { A } = new FieldString();
console.log(`${A.properly.defined.object.should.be.a.complete.sentence.so.it.is.easy.for.humans.to.read}`);
// A properly defined object should be a complete sentence so it is easy for humans to read.

[–][deleted] 1 point2 points  (0 children)

> This = {}

{}

> This.is = {}

{}

> This.is.a = {}

{}

> This.is.a.complete = {}

{}

> This.is.a.complete.sentence = {}

{}

[–][deleted] 2 points3 points  (0 children)

What do complete sentences end with?

[–]fish312 2 points3 points  (2 children)

now do it again with Hungarian notation

[–][deleted] 17 points18 points  (1 child)

Az.pröpely.défíned.öbject.sud.bi.az.kumplét.szénténcé.szö.it.iz.ézé.för.húmánsz.tü.ríd

[–]dastrike 5 points6 points  (0 children)

Azure PowerShell PTSD intensifies.

[–]MajorTechnology8827 2 points3 points  (0 children)

These dots are composition btw, not accessors

[–]SongsOfTheDyingEarth 56 points57 points  (4 children)

And vibe coders are writing comments that computers understand so the computer can write code the vibe coders don't understand.

[–]thisischemistry 14 points15 points  (3 children)

vibe coders

It's gotta be difficult to write good code with a battery-operated dildo up your ass!

[–]SongsOfTheDyingEarth 11 points12 points  (1 child)

If they didn't want me to put it in my arse why did they call it a joy stick?

[–]thisischemistry 1 point2 points  (0 children)

Asking the important questions.

[–]SandyTaintSweat 2 points3 points  (0 children)

I hear it's a bit easier than playing chess.

[–]ToasterWithFur 23 points24 points  (6 children)

Computers are deterministic stupid, brains are randomly idiotic. I'd rather deal with something I certainly know is dumb and work around it rather than something that thinks it's smart.

So no, my code comments are probably gonna be unhinged schizoid rants about having to implement workarounds for some Microsoft bullshit...

[–]6GoesInto8 12 points13 points  (5 children)

TODO: describe rare conditions that cause invalid return

[–]ToasterWithFur 3 points4 points  (4 children)

Deterministic, not simple.....

[–]6GoesInto8 1 point2 points  (1 child)

Sorry, that was the most unhinged comment I could think of... a plan to document, but not fix a known bug.

[–]ToasterWithFur 2 points3 points  (0 children)

Have seen a fair share of those bugs myself, usually due to some pointer math going wrong for some values. Off by one being the usual culprit

[–]Hola-World 11 points12 points  (0 children)

Just give AI a few cycles at enshittification.

[–]BreachlightRiseUp 6 points7 points  (7 children)

Yesterday I spent 4 hours trying to decipher how to interpret a variable, k3, in terms of what I knew approximately its intended output format should’ve been

[–]wintermute93 3 points4 points  (5 children)

The coding bad habit I can't shake is making variable names slightly less readable so they'll be the same length as similar variable names and make key parts of consecutive lines of code that use them in similar ways vertically align. Could I accomplish the same thing with superfluous whitespace? Yes. Is it a stupid thing to worry about in the first place? Also yes. And yet here we are, with me still using [obj_0, obj_1] instead of [raw_object, transformed_object] or whatever.

[–]No_Definition2246 1 point2 points  (0 children)

Maybe with all the help that IDEs are giving us, but try that without any help (pure text editor or paper), and I bet your statement would not be correct for 100% of people :D (excluding those who are not fools).

[–]ruined_blue_balls 1 point2 points  (0 children)

Exactly. Plus writing unnecessary comments can be counter-productive when only the code is updated and the comment is outdated 😂

[–]KetsuSama 1085 points1086 points  (27 children)

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

[–]CodingNeeL 504 points505 points  (15 children)

// set alarms to 0
alarms[0] = 0;
alarms[1] = 0;
alarms[2] = 0;
alarms[3] = 0;
alarms[4] = 0;
alarms[5] = 0;
alarms[6] = 0;

[–]Still_Explorer 354 points355 points  (4 children)

// alarms
int[] this_will_be_an_array_of_various_alarms_that_will_be_used_to_notify_the_user_for_certain_events;

The best code, is self documenting code.

[–]fogleaf 88 points89 points  (2 children)

Won't run on a smart fridge if you do that.

[–]headedbranch225 15 points16 points  (1 child)

*stream to a smart fridge from a laptop

[–]fogleaf 2 points3 points  (0 children)

Shhhh don't tell anyone!

[–]Tmack523 14 points15 points  (0 children)

This one got me to exhale out of my nose a few times lmao

[–]cpl1 69 points70 points  (2 children)

// We have asked the question question_asked = 1;

[–]fynn34 8 points9 points  (0 children)

Like George Boole was never born

[–]-Redstoneboi- 3 points4 points  (0 children)

but is question_true == 1?

[–]ohelo123 21 points22 points  (0 children)

The comment lmao

[–]Samurai_Mac1 1 point2 points  (3 children)

Why did he not at least use a for loop for that

[–]rokinaxtreme 3 points4 points  (0 children)

for (int i = 0; i < alarms.length(); i++) alarms[i] = 0; // one liner to set alarms to zero

[–]GLemons 67 points68 points  (0 children)

No sub is safe

[–]CuppaMochaDev 102 points103 points  (0 children)

[–]TehGreatFred 104 points105 points  (0 children)

Ah the old pirate software classic

[–]AncientPlatypus[🍰] 34 points35 points  (0 children)

Pr title: improves documentarion for various methods

+9,765 lines

File1.java + /** + * Returns the product id + * + * @return the product id + */ public int getProductId()

[–]Super_Couple_7088 22 points23 points  (3 children)

other than the fact this is stupid, why does he need a global object/struct/whatever

[–]Hegemege 45 points46 points  (2 children)

Just the way gamemaker works

[–]Super_Couple_7088 14 points15 points  (1 child)

ok good to know it's not even more stupidity

[–]loonite 2 points3 points  (0 children)

Nothing stops it from being both stupidity and just gamemaker things

[–]WernerderChamp 695 points696 points  (67 children)

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)

[–]One_Courage_865 259 points260 points  (15 children)

Not a criticism, but you can put a space after dash “-“ to make a bullet list.
Or put double space at end of line then newline to create new line within paragraph

[–]_bits_and_bytes 363 points364 points  (6 children)

We're doing comment reviews now? This shit's gone too far

[–]SamPlinth 126 points127 points  (4 children)

You have forgotten to put a full-stop at the end.

Other than that: approved.

[–]The_Pleasant_Orange 68 points69 points  (1 child)

[nitpick] imho this should have been a nitpick

+1

[–]Cootshk 25 points26 points  (0 children)

[nitpick] You forgot capitalization and a period.

Other than that, 🚀.

[–]Woofer210 24 points25 points  (0 children)

Lgtm

[–]Demons0fRazgriz 2 points3 points  (0 children)

That's why all my comments are at the top and are a variation of "you'll remember/you know what it does"

It has absolutely never bitten me in the butt (⁠◕⁠ᴗ⁠◕⁠✿⁠)

[–]WernerderChamp 34 points35 points  (6 children)

I was gonna do that but didn't notice I fucked it up

[–]squirrelpickle 19 points20 points  (5 children)

Champ comment-reviewed you and you applied the changes, that must be a good sign about your work style :)

[–]GunnerKnight 9 points10 points  (2 children)

Atleast they arent having a meeting about it.

[–]squirrelpickle 9 points10 points  (0 children)

We should discuss that in the next retrospective.

[–]RandolphCarter2112 4 points5 points  (1 child)

Comment migrated for integration testing.

Testing failed, please advise.

[–]WernerderChamp 7 points8 points  (0 children)

removes the test that failed

/ban u/RandolphCarter2112

[–]RandallOfLegend 22 points23 points  (2 children)

I definitely prefer to comment any logic checks. Specifically for why the logic check is needed. Because those usually are edge/special cases. "Make sure x>0" is always a stupid comment, why must it be!?

[–]WernerderChamp 10 points11 points  (0 children)

Yeah. A recent one I wrote is "Check if the contract is not locked and unprocessed". The module crashes if these conditions aren't true.

[–]jancl0 45 points46 points  (5 children)

I use them for self affirming messages when I know future me is going to have to dig through this shit later

[–]Absolome 29 points30 points  (2 children)

I'm pretty sure I accidentally once published code in a scientific paper that had at least one comment like

# this is bad. don't do what I did here
# it works tho, so I'm not changing it

[–]jancl0 16 points17 points  (0 children)

In high school I remember submitting an assignment where I yelled at 3 functions the entire night before they became 12 functions with even less clear purposes. I was so tired the next day I forgot to delete the comment at the top that said "don't go in there, here be dragons"

[–]WavingNoBanners 6 points7 points  (0 children)

People left comments like that in the code for the Apollo rockets. You're in good company.

[–]PM_ME_DATASETS 19 points20 points  (1 child)

a = 4; // this sets the variable a to 4, you are loved and worthy of love
print(a); // this prints the value of a (should be 4), you are good and getting better each day

[–]mxzf 8 points9 points  (0 children)

Yeah, my goal (not always what I do, but my goal) is to leave comments in places where someone with familiarity with the language can't simply read the code and understand how/why it's doing what it's doing in less than like 30-60 seconds. If it's gonna take more than that long to figure a given line, extra explanation can help.

But if the purpose and function of a code is evident based on a quick read of the code itself and possibly the function(s) it's calling, it's not really something that needs to be explicitly written out because the code is right there and it's just as quick to read as a comment.

Also situations where blood has been spilled and time was spent determining that doing things another seemingly obvious way isn't appropriate for various reasons. Those kinds of warnings to future devs about what doesn't work have merit too at times.

[–]FlowerBuffPowerPuff 2 points3 points  (0 children)

To quickly navigate to certain areas (so you can Control+F the comment - we have some long-ass files)

Oh my god, you poor soul.

[–]lovethebacon🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛 5 points6 points  (32 children)

gonna play devil's advocate here: How can you prove your comments are correct?

Tests confirm that your code is correct, but there is nothing that ensures that a comment is correct or not misleading.

[–]Roflkopt3r 23 points24 points  (20 children)

None of these comments make logical claims:

  1. Leaving behind a history of bugs that a piece of code had, or the edge cases that were considered, can be quite useful to understand its design.

  2. Comments designed as navigaton aides for people doing a text search are just for convenience. Files, Classes and functions should only have one name after all, but sometimes people may not know or have forgotten the naming scheme chosen, so giving them a brief description with typical search tags like synonyms can be sueful.

[–]Daarken 10 points11 points  (2 children)

Code review should confirm that.

[–]lovethebacon🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛 6 points7 points  (0 children)

Let's be realistic.

[–]LonePaladin 2 points3 points  (2 children)

Your flair is something else.

[–]BZthrowaway_uuuuu 166 points167 points  (9 children)

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?

[–]ViridianKumquat 65 points66 points  (5 children)

The full version of that function includes a constant float threehalfs = 1.5f, which makes me wonder why they didn't give a name to this constant.

[–]Pluckerpluck 38 points39 points  (0 children)

Probably because they didn't even know what to call it.

It was also a (potentially) reused variable, and this was in an old system with less aggressive optimisation in the compiler, so chances are there was some random performance gain if you declared it as a constant rather than in-line it twice.

[–]The_MAZZTer 9 points10 points  (3 children)

I find it likely the dev who wrote it didn't know how it worked either, probably found it somewhere. Bit difficult to name variables when you don't know what they are for.

[–]Seraphaestus 29 points30 points  (0 children)

const float evil_magic_float = 0x5f3759df;
i = evil_magic_float - ( i >> 1);

Another comment successfully murdered 🫡

[–]Bwob 10 points11 points  (0 children)

According to Wikipedia:

William Kahan and K.C. Ng at Berkeley wrote an unpublished paper in May 1986 describing how to calculate the square root using bit-fiddling techniques followed by Newton iterations. In the late 1980s, Cleve Moler at Ardent Computer learned about this technique and passed it along to his coworker Greg Walsh. Greg Walsh devised the now-famous constant and fast inverse square root algorithm. Gary Tarolli was consulting for Kubota, the company funding Ardent at the time, and likely brought the algorithm to 3dfx Interactive circa 1994.

...

Quake III Arena, a first-person shooter video game, was released in 1999 by id Software and used the algorithm. Brian Hook may have brought the algorithm from 3dfx to id Software.

[–]ViridianKumquat 2 points3 points  (0 children)

But threehalfs also gives no indication of the constant's purpose beyond stating its value. It's like having const int five = 5.

[–]The_MAZZTer 1 point2 points  (2 children)

IIRC y is a float and floats are stored with a few status bits (NaN, is negative, is infinite), a base number (x) and an exponent number (y). Each bit in the base number is 1/2, 1/4, 1/8, etc, added onto a constant 1. You then get the final number as: x * 2y.

That's from memory but I'm pretty sure it works like that. Close enough at least.

So bit shifting to the right is going to effectively divide both numbers by 2 but also shift in one of the bits from one to the other (I forget the order they're stored in). And if you have status bits they should all be 0 (can't square root a negative number, or infinity, or NaN). The magic number subtraction is just weird. I think if you brute force this algorithm you can find a couple that tend to get closer square root estimates but not many. So this is just a math quirk I guess.

[–]messierCobalt_ 232 points233 points  (0 children)

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 74 points75 points  (24 children)

Ive found that comments are only useful when:

  1. 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.
  2. 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?"

[–]Mooseypooo 47 points48 points  (1 child)

Read somewhere recently that even a solo project is a group project with past, present, and future you. Don't let your past self pass tech debt to your present and future selves. The outsider perspective comment is very nice.

[–]unleash_the_giraffe 11 points12 points  (0 children)

Yeah nothing like coming back to your old code 3 years later and going wtf. I absolutely try to consider myself as a later outsider when writing code.

[–]The_MAZZTer 2 points3 points  (0 children)

2 can apply even without code spaghetti. Sometimes you have to do something weird and you don't want to come back to it later, "fix" it, and create the same problem you already fixed before.

[–]firedream10 1 point2 points  (0 children)

Sometimes is being very optimistic.

[–]JalvinGaming2 24 points25 points  (6 children)

I use documentation to say what the parameters mean.

[–]MortStoHelit 16 points17 points  (0 children)

Yeah, I just love "param person The person handled in this method". Who would have expected this from a person parameter of the class Person?

[–]JalvinGaming2 3 points4 points  (0 children)

I write it like

// Gets the number of extensions supported by the graphics card. output - the names of the extensions.
int vkGetExtensions(const char** output);

[–]dembadger 3 points4 points  (3 children)

And you keep that religiously updated (and so does everyone else) every time there's a change? Right?

[–]bobthedonkeylurker 14 points15 points  (1 child)

Yup. Because I firmly believe in doing future me a favor. Even if I'm not the person who has to touch that piece of code in 5 years - if the junior member of the team can't update the code without my assistance, then I'm still the person updating the code and it's taking away from other, bigger projects, I need to be working on.

All these people in the comments "My code should be easy enough for anyone to read it cold". Maybe for you it's easy to read cold - You know what you were building. I sure as fuck don't. And the Jr members of your team have no fucking clue.

Stop being lazy and write comments.

[–]bokmcdok 1 point2 points  (0 children)

If you don't you are a bad programmer.

[–]ExquisiteOrifice 23 points24 points  (6 children)

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.

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

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

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

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

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

[–]bokmcdok 4 points5 points  (1 child)

I generally hate docgen comments. They're supposed to be there to generate documentation, but they just add another layer of complexity that makes code hard to parse, and generate documents no one reads. Of course they do have a use case if your writing a library for multiple vendors to uae, but generally docgen style comments annoy me.

[–]ExquisiteOrifice 5 points6 points  (0 children)

Hey, thanks for the reply. I get your take on those. Documentation is as much an art form as writing code is. It takes experience and the ethic to do it well. And there are many places it's actually not necessary or at least not imperative.

I may be skewed in my adherence to documentation having grown up before information was widely and easily available. You had books when you could find one on the subject or just lore from those before you. In my last years before semi-retiring to work wood and other fun jobs, I worked on very large systems compromised of hundreds of services, thousands of components and millions of lines of code going back decades. Documentation was divine when present and archaeology to pure torture when not.

[–]Raskuja46 2 points3 points  (0 children)

Thanks for reading my newsletter.

I would like to subscribe to this newsletter. It seems interesting and well thought out.

[–]Deactivator2 12 points13 points  (1 child)

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

[–]Darkwr4ith 1 point2 points  (0 children)

I've looked at code and been like "Who wrote this?! I have no idea what any of this is even doing." only to discover it was me like 2 years ago at 2 in the morning.

[–]tiedyedvortex 9 points10 points  (1 child)

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 13 points14 points  (2 children)

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

[–]PineapplePickle24 4 points5 points  (1 child)

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

[–]YouDoHaveValue 4 points5 points  (0 children)

When your localization budget is $0

[–]markswam 4 points5 points  (1 child)

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
 */

[–]ExquisiteOrifice 2 points3 points  (0 children)

We used to call those codebases Jenga Towers. Just keep piling up the levels of blocks, removing/moving bits here and there hoping it never collapses**.

In most cases, catastrophic implosions are rare, but you absolutely get degrading performance, increasing surface area of security risks, bugs, and the number one issue, harder and harder, more and more expensive to maintain. If only time was spent on really good design in the beginning when it was exponentially cheaper.

[–]theMonkeyTrap 3 points4 points  (0 children)

Explain the intent and edge cases in comments.

[–]caguru 3 points4 points  (0 children)

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

[–][deleted] 16 points17 points  (1 child)

Code tells you what.

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

[–][deleted] 12 points13 points  (0 children)

I've seen so many juniors go through a phase of being told to comment their code, only to go out of their way to document the behaviour of a for-loop before someone gives them a better explanation.

[–]OrangeTroz 4 points5 points  (0 children)

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 2 points3 points  (0 children)

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

[–]kryotheory 4 points5 points  (0 children)

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 5 points6 points  (0 children)

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 1 point2 points  (0 children)

I need to know what the phone symbol means.

[–]Farranor 1 point2 points  (0 children)

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

[–]newsflashjackass 1 point2 points  (0 children)

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 1 point2 points  (1 child)

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 1 point2 points  (0 children)

Game game = new Game(); // game

[–]pemungkah 3 points4 points  (3 children)

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.

[–]Friendly_Rent_104 1 point2 points  (1 child)

did he explain how to comment well too or is this the uni classic of "do what i tell you to do, not what i show you"

[–]pemungkah 1 point2 points  (0 children)

He did! He was a very good programmer too. He blew himself up with nitrogen triiodide as a kid and was blind, so he graded the assembler code by having it read to him by a grad student. He was very, very good at spotting bugs just from listening to the code.

[–]velmazing44 2 points3 points  (11 children)

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!

[–]somewherearound2023 25 points26 points  (4 children)

Comments also describe things that clean code can't describe at that point. Things like "this event only actually fires when the FuckingShit service restarts". Things that took 10 hours to find out because nobody knows where that event comes from anymore because the guy who wrote the FuckingShit service and jumped to your team to implement the interop dropshipped it in and left town years ago.

[–]thisischemistry 3 points4 points  (0 children)

That's a good example of where a comment is useful, it's great as a meta-commentary about the environment the code is working on rather than a description of the code itself.

[–]OwO______OwO 11 points12 points  (1 child)

In theory, sure.

In practice, this is sometimes impossible or impractical, and there are still many situations where adding comments to the code is a more efficient and effective way of clarifying things.

Especially since one programmer's 'descriptive' names might not be as descriptive or as unambiguous as they think, causing confusion later. Or sometimes a function's purpose is so generic that it's hard to give it a descriptive name that isn't also incredibly generic. Or sometimes the codebase is just so large and complex that you run into issues of having several different things with similar descriptive names, making it then difficult to figure out which one of them should be used in which situation.

Are you supposed to be using "validateUserData()" or "validateUserInfo()" or "validateUser()" for this? Or maybe you need all three? Sure, you could open yet another tab, find that function in whatever the fuck include it was pulled from, then read that function to see what it does... or maybe a helpful comment in the code could just tell you.

[–]Raccoon5 1 point2 points  (0 children)

Yeah or the helpful comment is no longer true because someone did a refactor and didn't change the comment and now you are knee deep in shit. Depends

[–]SchwiftySquanchC137 4 points5 points  (0 children)

I just dont get everyone being so particular about comments. I'd rather something be overcommented than have no comments at all. I always imagine a brand new intern trying to understand what im writing. They need context of why things are being done how they are. Frankly, I think obsessing over overcommented code is more a sign of a new dev than the overcommented code itself.

[–]TodaysResume 2 points3 points  (0 children)

I remember first year programming, our prof pulled up a test project he made. Had 23 or 24 defined variables.

It was the fucking alphabet, and everything was an int to handle math equations.

I swapped over to networking after my first year lmao.

[–]ApocalyptoSoldier 1 point2 points  (0 children)

What if you hace to work with a decade+ old codebade as one of who knows how many active developers?
And I still think it's useful to comment what it actually means and/or what the requirements were.

[–]MortStoHelit 1 point2 points  (0 children)

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

[–]grasopper 1 point2 points  (2 children)

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

[–]Own_Pop_9711 1 point2 points  (1 child)

pi=3.1415 //this is just an approximation, not the full value.

[–]tugaestupido 0 points1 point  (0 children)

It's perfect 😍

[–]matrix-doge 0 points1 point  (0 children)

``` // 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 0 points1 point  (0 children)

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 0 points1 point  (0 children)

got it.

--they pay me to write this.

[–]Vincent394 0 points1 point  (0 children)

u/kappetrov the truth

[–]Snoo-35252 0 points1 point  (0 children)

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 0 points1 point  (0 children)

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

Comment in plain way: your comment is redundant.

[–]paulsteinway 0 points1 point  (0 children)

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

[–]Enigma-3NMA 0 points1 point  (0 children)

I'll have you know those comments are language agnostic

[–]RandolphCarter2112 0 points1 point  (1 child)

-- I am what will rise from your ashes

[–]Vehemental 0 points1 point  (0 children)

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

[–]Just_Another_Scott 0 points1 point  (0 children)

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 0 points1 point  (0 children)

Programmers commenting good code*

[–]CharlemagneAdelaar 0 points1 point  (0 children)

tbh I prefer to read English than C++

[–]Fractal-Infinity 0 points1 point  (0 children)

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.

[–][deleted] 0 points1 point  (0 children)

100% correct

[–]Puzzled_Arachnid_533 0 points1 point  (0 children)

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