If your code needs comments, it's either because it's unnecessarily complex/convoluted, or because there's more thought in it (e.g. complex mathematic operations, or edge-cases etc.). Comments just often don't age well IME, and when people are "forced" to read the (hopefully readable) code, they will more likely understand what is really happening, and the relevant design decisions.

Good video I really recommend: https://www.youtube.com/watch?v=Bf7vDBBOBUA

[–] astraeus@programming.dev 17 points 10 months ago* (last edited 10 months ago) (7 children)

This mindset is good, but unfortunately enforces bad programmers to leave their undocumented code in critical places where someone eventually has to figure out what the hell they were doing or refactor the whole damn thing because they got promoted to middle-management and can’t remember why they even wrote it.

[–] magic_lobster_party@kbin.social 5 points 10 months ago (6 children)

Chances are that the comments quickly turn out of date and become incorrect. Misleading comments is worse than no comments.

[–] heikomat@lemmy.world 5 points 10 months ago

If the comments tell you "what" happens, then yes, they can geht outdated fast. The details of how something works can change quickly.

But comments documenting "why" something is done (a certain way) - explaining the intent - are probably valid for mich longer.

In the best case comments aren't viewed as something that is seperate from the code, but part of it. So that if someone changes the code, the comments has to be checked aswell (if the explanation of "why" something is done actually changed).

load more comments (5 replies)

load more comments (40 replies)