☆ Yσɠƚԋσʂ ☆@lemmy.ml to Programmer Humor@lemmy.mlEnglish · 12 days agoWhen I'm asked to write documentationlemmy.mlimagemessage-square2fedilinkarrow-up13arrow-down10
arrow-up13arrow-down1imageWhen I'm asked to write documentationlemmy.ml☆ Yσɠƚԋσʂ ☆@lemmy.ml to Programmer Humor@lemmy.mlEnglish · 12 days agomessage-square2fedilink
minus-squaremagic_lobster_party@fedia.iolinkfedilinkarrow-up1·12 days 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.
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.