ProgrammerHumor

iMeanItsNotWrong

iMeanItsNotWrong
https://i.redd.it/qe3ttm00ledf1.png
Reddit

Discussion

Gadshill

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

2 days ago
big_guyforyou
:py:

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

2 days ago
holchansg

return x

2 days ago
big_guyforyou
:py:

sorry, not capitalized, therefore not a sentence

2 days ago
smokesick
:unreal::cp::py:

return sex

2 days ago
Suitable_Annual5367

Too late. Long gone for you.

2 days ago
MegaIng
  • has been garbage collected already.
1 day ago
Dexteroid

None

2 days ago
GunnerKnight

Error: sex has not been initialized before return

1 day ago
entropic

NullPointerException

1 day ago
tagkiller

Return ret;

2 days ago
Snudget
:rust::py::asm:

Remove the dots and you have the minimum required java class name

2 days ago
Roflkopt3r

With the dots, it's the minimum required java namespace.

2 days ago
Giwaffee

Remove dots everywhere and you have the average redditor that doesn't use interpunction

1 day ago
Ishbane
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;
}
2 days ago
carcinoTerror

This is horrible. I love it

1 day ago
Makefile_dot_in
:rust:

js unit test frameworks be like

2 days ago
tree_cell

missing a period

2 days ago
doStuffStruck1905

Programmer on menopause

1 day ago
AngelLeliel

literate programming

2 days ago
big_guyforyou
:py:

i'm a pro-grammar programmer

2 days ago
AnalBlaster700XL

Oldtimers as me remembers ”Clean Code” by Robert C. Martin.

2 days ago
TA-F342

ForSaleBabyShoesNeverWorn.cs

2 days ago
10BillionDreams

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.
1 day ago
big_guyforyou
:py:

> This = {}

{}

> This.is = {}

{}

> This.is.a = {}

{}

> This.is.a.complete = {}

{}

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

{}

1 day ago
SoCuteShibe

What do complete sentences end with?

2 days ago
fish312

now do it again with Hungarian notation

2 days ago
big_guyforyou
:py:
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
2 days ago
dastrike
:cs:

Azure PowerShell PTSD intensifies.

1 day ago
MajorTechnology8827
:hsk:

These dots are composition btw, not accessors

2 days ago
SongsOfTheDyingEarth

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

2 days ago
thisischemistry

vibe coders

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

2 days ago
SongsOfTheDyingEarth

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

1 day ago
thisischemistry

Asking the important questions.

1 day ago
SandyTaintSweat

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

1 day ago
ToasterWithFur
:lua::c::asm:

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

2 days ago
6GoesInto8

TODO: describe rare conditions that cause invalid return

2 days ago
ToasterWithFur
:lua::c::asm:

Deterministic, not simple.....

2 days ago
6GoesInto8

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

2 days ago
ToasterWithFur
:lua::c::asm:

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

2 days ago
Hola-World
:j:

Just give AI a few cycles at enshittification.

2 days ago
BreachlightRiseUp

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

2 days ago
wintermute93

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.

2 days ago
War_Raven

Adjust all you variables along the widest one

raw_________object

transformed_object

2 days ago
wintermute93

thanks, i hate it

2 days ago
No_Definition2246

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

2 days ago
[deleted]

[removed]

2 days ago
KetsuSama
//storyline 419
global.storyline_array[419] = 0;
2 days ago
CodingNeeL
// 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;
2 days ago
Still_Explorer
// 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.

1 day ago
fogleaf

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

1 day ago
headedbranch225

*stream to a smart fridge from a laptop

1 day ago
Tmack523

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

1 day ago
cpl1

// We have asked the question question_asked = 1;

1 day ago
fynn34

Like George Boole was never born

1 day ago
-Redstoneboi-
:rust::py::js::j::cp::c:

but is question_true == 1?

1 day ago
ohelo123

The comment lmao

1 day ago
Samurai_Mac1
:p::py::msl::js::ts::cs:

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

1 day ago
rokinaxtreme
:gd::s::p::py::cp::js:

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

1 day ago
GLemons

No sub is safe

2 days ago
CuppaMochaDev

2 days ago
TehGreatFred

Ah the old pirate software classic

2 days ago
AncientPlatypus

Pr title: improves documentarion for various methods

+9,765 lines

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

1 day ago
Super_Couple_7088

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

1 day ago
Hegemege

Just the way gamemaker works

1 day ago
Super_Couple_7088

ok good to know it's not even more stupidity

1 day ago
loonite
:js::ts::py::lua::g:

Nothing stops it from being both stupidity and just gamemaker things

1 day ago
WernerderChamp
:g::j:

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)
2 days ago
One_Courage_865
:py:

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

2 days ago
_bits_and_bytes
:py:

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

2 days ago
SamPlinth
:gd::cs::cake:

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

Other than that: approved.

2 days ago
The_Pleasant_Orange

[nitpick] imho this should have been a nitpick

+1

1 day ago
Cootshk
:lua::re::py::bash:

[nitpick] You forgot capitalization and a period.

Other than that, 🚀.

1 day ago
Woofer210
:ts::js::j::py:

Lgtm

1 day ago
Not-the-best-name
:py:

Just fucking send it

1 day ago
Demons0fRazgriz

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 (⁠◕⁠ᴗ⁠◕⁠✿⁠)

1 day ago
WernerderChamp
:g::j:

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

2 days ago
squirrelpickle

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

1 day ago
GunnerKnight

Atleast they arent having a meeting about it.

1 day ago
squirrelpickle

We should discuss that in the next retrospective.

1 day ago
RandolphCarter2112
:COBOL:

Comment migrated for integration testing.

Testing failed, please advise.

1 day ago
WernerderChamp
:g::j:

removes the test that failed

/ban u/RandolphCarter2112

1 day ago
RandallOfLegend
:cs::m::rust::py:

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!?

2 days ago
WernerderChamp
:g::j:

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.

2 days ago
jancl0

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

2 days ago
Absolome

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
1 day ago
jancl0

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"

1 day ago
WavingNoBanners
:py::c::cp::cs:

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

1 day ago
PM_ME_DATASETS
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
1 day ago
mxzf

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.

2 days ago
FlowerBuffPowerPuff

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.

1 day ago
lovethebacon
🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛

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.

2 days ago
Roflkopt3r

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.

2 days ago
Daarken

Code review should confirm that.

2 days ago
lovethebacon
🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛🦛

Let's be realistic.

2 days ago
LonePaladin

Your flair is something else.

2 days ago
BZthrowaway_uuuuu

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?
2 days ago
ViridianKumquat

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.

2 days ago
The_MAZZTer
:cs:

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.

1 day ago
Seraphaestus
:cs:
const float evil_magic_float = 0x5f3759df;
i = evil_magic_float - ( i >> 1);

Another comment successfully murdered 🫡

1 day ago
Bwob

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.

1 day ago
ViridianKumquat

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

1 day ago
Pluckerpluck
:py::js::j::c:

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.

1 day ago
The_MAZZTer
:cs:

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.

1 day ago
messierCobalt_

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

2 days ago
unleash_the_giraffe

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

2 days ago
Mooseypooo

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.

2 days ago
unleash_the_giraffe

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.

2 days ago
pinkycatcher

Highly disagree. I've had to rely on my comments when I'm the sole maintainer of my code, where there was no bug, and where it's a stand alone script or query.

Any time you have to modify code you have to go relearn it, comments help you get on the right path again.

Also any time I have to do advance logic to get the result I need, I'm not going to remember that shit, just write it down.

2 days ago
SyrusDrake
:gd: :py:

Yea, that's what I don't quite understand about "self-documenting code". Is following abstract logic written for a machine really easier than reading a quick summary of what code does?

2 days ago
pinkycatcher

Right? I'd much rather have someone's chain of thought as they're writing like "Now I need to call this other piece of code to do X" and "Now the data is aligned to match the formatting of this other data so we can finally join it with any issues" than to deal with actually deep reading the code and wonder why the fuck this guy uses three letter variables, or he's using what seems like a very clear term but in a specific jargon which is different than how it's normally used ever so slightly.

2 days ago
bobthedonkeylurker
:py::msl::r:

Fuck me, I don't even remember my chain of thought when looking at code I wrote 6 months ago. Comments help me regain that chain of thought super fast. So now my updates/edits/etc can be much more efficiently performed.

And I can pass that off to other team members who definitely have no clue what my train of thought was at the time I was writing the code.

2 days ago
mxzf

Is following abstract logic written for a machine really easier than reading a quick summary of what code does?

Sometimes, yeah.

Because I've absolutely come across situations where the comments about what the code should do didn't match what the code actually does, either due to the code being edited but not the comment or because the person writing the comment misunderstood a nuanced aspect of the code.

Code never lies, it'll always be the ultimate truth of what's actually running (even if it's not quite what you thought it was, but that's human error rather than the code lying to you like comments can).

And if the code is clean and logical, it can often be just as quick to read a line or two of code as it is to read a sentence or two of comments to explain it.

2 days ago
SyrusDrake
:gd: :py:

I mean, that's fair, but just do both, then? If my device doesn't work, I might open it to see if it's broken, and I'll appreciate it if it's designed well to make that process easy. But I'm still going to read the manual first.

2 days ago
Crazyjaw

Sounds good in principle but generally people change the code and don’t change the comments. Might be a small change but over time the comments can outright deceive you. Even if one in a dozen is misleading, it quickly just makes more sense to make your actual code readable rather than maintain two “versions” of it, the English and the real thing

2 days ago
bobthedonkeylurker
:py::msl::r:

Then hire better people and/or train your people better. That's the shittiest excuse to not do your own part properly.

2 days ago
The_MAZZTer
:cs:

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.

1 day ago
firedream10

Sometimes is being very optimistic.

2 days ago
JalvinGaming2

I use documentation to say what the parameters mean.

2 days ago
MortStoHelit

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?

2 days ago
JalvinGaming2

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);

1 day ago
dembadger

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

2 days ago
bobthedonkeylurker
:py::msl::r:

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.

2 days ago
bokmcdok

If you don't you are a bad programmer.

1 day ago
ExquisiteOrifice

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.

2 days ago
bokmcdok

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.

1 day ago
ExquisiteOrifice

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.

1 day ago
Raskuja46

Thanks for reading my newsletter.

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

1 day ago
Deactivator2

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

2 days ago
Darkwr4ith

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.

1 day ago
carorinu

Am I the only one using comments mostly to be able to search it more easily in the future lol

2 days ago
Falkster123

Arent your function/file names explictit enought?

2 days ago
One_Courage_865
:py:

Nah my file names are too tame to be explicit

2 days ago
YesterdayDreamer

But the guy asked about it being "explictit", too shy about the tits too?

2 days ago
carorinu

unfortunately not at a glance and from the name, self taught, write some automation once or twice a year guidelines are being followed lol

2 days ago
tiedyedvortex

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.

2 days ago
nirgle
// Close the file.
file.Close();
2 days ago
kevin7254

Every LLM ever

1 day ago
PineapplePickle24
:cp:

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

2 days ago
YouDoHaveValue

When your localization budget is $0

1 day ago
markswam
:cs::j::py::rust::bash:

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
 */
2 days ago
ExquisiteOrifice

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.

1 day ago
theMonkeyTrap

Explain the intent and edge cases in comments.

2 days ago
caguru

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

1 day ago
Throwaway_987654634

Code tells you what.

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

2 days ago
hammer_of_grabthar

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.

2 days ago
OrangeTroz

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.

2 days ago
dookalion

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

1 day ago
kryotheory
:j:

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.

1 day ago
the-judeo-bolshevik
:c::g:

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.

2 days ago
atomic_redneck

I need to know what the phone symbol means.

2 days ago
Farranor

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

2 days ago
newsflashjackass

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.

1 day ago
Darkwr4ith

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.

1 day ago
Fearless_Baseball121

If anyone wanna know, this is the quick use guide for a Plantronics calisto 620

1 day ago
one_last_cow

Game game = new Game(); // game

23 hours ago
pemungkah

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.

1 day ago
Friendly_Rent_104

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"

1 day ago
pemungkah

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.

1 day ago
velmazing44
:vb:

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!

2 days ago
somewherearound2023

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.

2 days ago
thisischemistry

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.

2 days ago
OwO______OwO

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.

2 days ago
Raccoon5

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

1 day ago
pinkycatcher

Disagree, there's no reason to not use clearly named code and comments. I've never been sitting down writing code and thought to myself "Oh man, if only I didn't comment my code I could have finished this today"

Comments are just the thought process that goes into the code, and also ideally the business process you need to perform, that way whoever comes in after knows why you wrote something the way you and and if they know the business function they know how they can change things without causing further issues.

2 days ago
SchwiftySquanchC137

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.

1 day ago
TodaysResume

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.

2 days ago
ApocalyptoSoldier
:cs::powershell::js:

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.

2 days ago
MortStoHelit

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

2 days ago
grasopper

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

1 day ago
Own_Pop_9711

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

1 day ago
tugaestupido
:j:

It's perfect 😍

2 days ago
matrix-doge
:j:

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

2 days ago
GromOfDoom

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.

2 days ago
Awkward_Tick0

got it.

--they pay me to write this.

2 days ago
Vincent394
:cs::c::cp::g:

u/kappetrov the truth

2 days ago
Snoo-35252

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.

2 days ago
Patrick_Atsushi

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

Comment in plain way: your comment is redundant.

1 day ago
paulsteinway

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

1 day ago
Enigma-3NMA

I'll have you know those comments are language agnostic

1 day ago
RandolphCarter2112
:COBOL:

-- I am what will rise from your ashes

1 day ago
Vehemental

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

1 day ago
Just_Another_Scott

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!

1 day ago
levimic
:ts:

Programmers commenting good code*

1 day ago
CharlemagneAdelaar

tbh I prefer to read English than C++

1 day ago
Fractal-Infinity

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.

1 day ago
baltimooree

100% correct

1 day ago
Specialist_Brain841

declarative vs imperative

22 hours ago
Puzzled_Arachnid_533

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

21 hours ago
AbjectAd753

my most random coment says:

```//the thing that do that other thing... whatever```

20 hours ago
rustyredditortux
:j:

comments are almost exclusively apologies for bad code

19 hours ago
sammy-taylor
:js::elixir-vertical_4::cp:

The “why”:

this “volume up” button is here because users need to be able to turn up the volume
13 hours ago
quick1brahim
:cs:

I write comments and summaries for things that are conceptually important for performance, but difficult to grasp. Things like dictionaries of dictionaries, jagged arrays, algorithms, methods that sometimes require a helper method, methods that return a bool but do something else and the bool just confirms if it was successful.

Code also deserves comments if it enables networking, multithreading, asynchronous behaviors, or other things that have potentially uncertain results.

11 hours ago
No-Pangolin-52

Instant classic

8 hours ago
morbuz97

Ill start writing comments as soon as compilers are able to verify them

3 hours ago