Am I the only one who likes to write comments when I find code that took me a while to understand even when I didn't write the code? It helps me when I go back to that place and it helps other devs that have to do the same figuring things out as me. Idk if I'm just weird but I really like writing documentations and commenting my code
You're definitely not the only one.
In my opinion the important information we should record in comments is WHY, because the code can only explain HOW, maybe WHEN, but never WHY. If we don't know WHY, any refactoring done in the future could break the logic by ignoring assumptions made by the authors.
// because I said so.
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.
I think comments are good in a first resort, along with the other points you mentioned. To me reading a single line summary and or explainer will always be faster than reading 15 lines of code even if it's very well made and self documenting
In doing this as well, for the same reason
If the docs I have to write are long enough I will include a small diatribe about a ancient pop-culture hill I'm still willing to die on, just to see if anyone notices.
It funny because yesterday the chess did not, in fact, speak for itself
It did, and it said he wasn't better than Magnus or Hikaru
Well I don't speak parseltongue
