158
When I'm asked to write documentation (lemmy.ml)
submitted 1 week ago by yogthos@lemmy.ml to c/programmerhumor@lemmy.ml
16 comments fedilink hide all child comments
top 16 comments
sorted by: hot top controversial new old
[-] independantiste@sh.itjust.works 19 points 1 week ago* (last edited 1 week ago)

Am I the only one who likes to write comments when I find code that took me a while to understand even when I didn't write the code? It helps me when I go back to that place and it helps other devs that have to do the same figuring things out as me. Idk if I'm just weird but I really like writing documentations and commenting my code

[-] pfm@scribe.disroot.org 8 points 1 week ago

You're definitely not the only one.

In my opinion the important information we should record in comments is WHY, because the code can only explain HOW, maybe WHEN, but never WHY. If we don't know WHY, any refactoring done in the future could break the logic by ignoring assumptions made by the authors.

[-] el_abuelo@programming.dev 2 points 1 week ago

// because I said so.

[-] magic_lobster_party@fedia.io 5 points 1 week ago

I think comments are good as a last resort when it’s difficult to communicate the intention of the code with other means.

If I find code that’s hard to understand, I’ll first try to find better variable or function names. Often this is enough.

If it’s still too difficult to understand, I try to restructure the code to better communicate the flow of the code.

If that doesn’t help (or is too difficult), then I might add a comment explaining key information that’s difficult to understand from the code.

[-] independantiste@sh.itjust.works 3 points 1 week ago* (last edited 1 week ago)

I think comments are good in a first resort, along with the other points you mentioned. To me reading a single line summary and or explainer will always be faster than reading 15 lines of code even if it's very well made and self documenting

[-] pfm@scribe.disroot.org 2 points 1 week ago

As mentioned in my other comment, names will rarely explain the reasons why a given solution was chosen. These reasons are important from maintenance perspective and should be recorded next to the relevant code.

[-] magic_lobster_party@fedia.io 2 points 1 week ago

I agree, and I count that as “key information that’s difficult to understand from the code”.

IMO, comments should be used to provide value to the code. If they’re used too much, then readers of the code will more likely stop reading them altogether. They already got what they need from the code itself and the comments usually don’t add much value.

If they’re sparse, then that’s a good indication they’re important and shouldn’t be missed.

[-] pfm@scribe.disroot.org 1 points 6 days ago

I definitely agree that too many comments is often a bad sign, esp. when large part of them is obviously generated.

[-] lord_ryvan@ttrpg.network 1 points 1 week ago

In doing this as well, for the same reason

[-] Bishma@discuss.tchncs.de 14 points 1 week ago

If the docs I have to write are long enough I will include a small diatribe about a ancient pop-culture hill I'm still willing to die on, just to see if anyone notices.

[-] chumbalumber@lemmy.blahaj.zone 5 points 1 week ago

It funny because yesterday the chess did not, in fact, speak for itself

[-] Kanda@reddthat.com 6 points 1 week ago

It did, and it said he wasn't better than Magnus or Hikaru

[-] chumbalumber@lemmy.blahaj.zone 5 points 1 week ago

The sheer pleasure in watching an arrogant tit get humbled was chef's kiss. Once by someone who couldn't give a shit about him, and was good enough to simply crush him the first few games and then dick about, and once by someone who really wanted a statement victory

[-] Kanda@reddthat.com 2 points 1 week ago

It was pretty good. Second arc in a year or so?

[-] chumbalumber@lemmy.blahaj.zone 1 points 1 week ago

Fingers crossed!

[-] lowleveldata@programming.dev 3 points 1 week ago

Well I don't speak parseltongue

this post was submitted on 08 Sep 2024
158 points (97.0% liked)

Programmer Humor

32024 readers
1387 users here now

Post funny things about programming here! (Or just rant about your favourite programming language.)

Rules:

founded 5 years ago
MODERATORS
AgreeableLandscape@lemmy.ml
cat_programmer@lemmy.ml