☆ Yσɠƚԋσʂ ☆@lemmy.ml to Programmer Humor@lemmy.mlEnglish · 2 years agoWhen I'm asked to write documentationlemmy.mlimagemessage-square3linkfedilinkarrow-up18arrow-down10
arrow-up18arrow-down1imageWhen I'm asked to write documentationlemmy.ml☆ Yσɠƚԋσʂ ☆@lemmy.ml to Programmer Humor@lemmy.mlEnglish · 2 years agomessage-square3linkfedilink
minus-squaremagic_lobster_party@fedia.iolinkfedilinkarrow-up1·2 years agoI 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.
minus-squarepfm@scribe.disroot.orglinkfedilinkarrow-up1·2 years agoAs 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.
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.
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.