☆ Yσɠƚԋσʂ ☆@lemmy.ml to Programmer Humor@lemmy.mlEnglish · 3 months agoWhen I'm asked to write documentationimagemessage-square3fedilinkarrow-up11arrow-down10
arrow-up11arrow-down1imageWhen I'm asked to write documentation☆ Yσɠƚԋσʂ ☆@lemmy.ml to Programmer Humor@lemmy.mlEnglish · 3 months agomessage-square3fedilink
minus-squaremagic_lobster_party@fedia.iolinkfedilinkarrow-up0·3 months 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·3 months 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.