1505

How programmers comment their code (lemmy.dbzer0.com)

submitted 1 week ago by Andromxda@lemmy.dbzer0.com to c/programmer_humor@programming.dev

146 comments fedilink hide all child comments

https://nitter.poast.org/denicmarko/status/1774077890281267451

top 50 comments

sorted by: hot top controversial new old

[-] zerofk@lemm.ee 3 points 6 days ago* (last edited 6 days ago)

Our code base is filled with “//constructor”, “//destructor”, “//assignment”, or the ever enlightening “Foo GetFoo(); // GetFoo”.

This is not what they mean by self-documenting code.

[-] ClassifiedPancake@discuss.tchncs.de 3 points 6 days ago

At work we let Typescript and descriptive naming document our code. Only when something is a workaround or otherwise weird will we add comments. So far it has worked great for us.

[-] Honytawk@lemmy.zip 226 points 1 week ago

Same with BIOS descriptions.

FGTSAB switch [toggles the FGTSAB setting]

infuriating

load more comments (11 replies)

[-] SlopppyEngineer@lemmy.world 126 points 1 week ago

Best comment ever was "It used to work like this but person at client demanded it work like that on this date" when the client complained it shouldn't work like that.

[-] tiredofsametab@kbin.run 1 points 6 days ago

I was porting our old code from PHP to Go at a previous company. I laughed as I copied my then-six-year-old comment "I'm promised by xxxxx that this is a temporary measure ".

[-] conciselyverbose@sh.itjust.works 135 points 1 week ago

That's basically what comments are most useful for. When you're doing something that's not obvious, and want to make sure the "why" doesn't get lost to time.

[-] kubica@fedia.io 93 points 1 week ago

// I'm not really that dumb, there is a reason.

[-] DarkDarkHouse 41 points 1 week ago

// narrator: the reason was management

load more comments (2 replies)

load more comments (3 replies)

[-] 0x0@lemmy.dbzer0.com 66 points 1 week ago

The best comments are "why" comments, the runner up is "how" comments if high-level enough, and maybe just don't write "what" comments at all because everyone reading your code knows how to read code.

load more comments (3 replies)

[-] yetAnotherUser@discuss.tchncs.de 112 points 1 week ago

/*
 * Gets stupidFuckingInteger
 *
 * @returns stupidFuckingInteger
*/
public double getStupidFuckingInteger() {
    return stupidFuckingInteger;
}

load more comments (7 replies)

[-] cupcakezealot@lemmy.blahaj.zone 76 points 1 week ago* (last edited 1 week ago)

//@TODO document this function later

15 years later

load more comments (1 replies)

[-] mundane@feddit.nu 70 points 1 week ago

Comments should explain "why", the code already explains "what".

[-] smeg@feddit.uk 60 points 1 week ago* (last edited 1 week ago)

The allowable exception is when the what is a what the fuck, as in you had to use a hack so horrible that it requires an apology comment

load more comments (3 replies)

load more comments (8 replies)

[-] AlexCory21@lemmy.world 62 points 1 week ago

I had a old job that told me that code is "self documenting" if you write it "good enough". And that comments were unnecessary.

It always annoyed the heck out of me. Comments are imo more helpful than hurtful typically.

Is it just me? Or am I weird? Lol.

[-] englislanguage 1 points 6 days ago

One example for self documenting code is typing. If you use a language which enforces (or at least allows, as in Python 3.8+) strong typing and you use types pro actively, this is better than documentation, because it can be read and worked with by the compiler or interpreter. In contrast to documenting types, the compiler (or interpreter) will enforce that code meaning and type specification will not diverge. This includes explicitly marking parameters/arguments and return types as optional if they are.

I think no reasonable software developer should work without enforced type safety unless working with pure assembler languages. Any (higher) language which does not allow enforcing strong typing is terrible.

[-] alonely0@programming.dev 51 points 1 week ago* (last edited 1 week ago)

Document intentions and decisions, not code.

[-] VonReposti@feddit.dk 39 points 1 week ago

Code should always by itself document the "how" of the code, otherwise the code most likely isn't good enough. Something the code can never do is explain the "why" of the code, something that a lot of programmers skip. If you ever find yourself explaining the "how" in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.

For me, that's what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.