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

[–] Pickle_Jr@lemmy.dbzer0.com 53 points 10 months ago (6 children)

Yeah, another way I've heard it phrased is comments are for explaining why you did things a certain way, not for explaining what it's doing.

[–] heikomat@lemmy.world 16 points 10 months ago* (last edited 10 months ago) (1 children)

Exactly that! Everyone can See "what" is happening, the code is right there. But the code usually doesn't tell you "why" that is happening - good comments help understand the authors intent and give context, so you don't have to guess.

Good comments should explain the things that are not obvious.

Good comments more than once prevented me from accidentially undoing a fix.

[–] nilloc@discuss.tchncs.de 2 points 10 months ago* (last edited 10 months ago)

Yup my comments are generally along the lines of:

I could have done this X way, but it ran slower
I was running out of time so this it’s mostly copied from (stack overflow url)
refactor when time allows

This is a side effect of doing lots of tiny websites , microcontroller code and mini web apps for under budgeted marketing projects with constantly changing designs and requirements that don’t need to last too long.

load more comments (4 replies)

load more comments (40 replies)