4 ms·

One instance where I've found writing lots and lots of comments helpful is for functions with code that I'm writing for the first time. It's like rubber-duck tr

One instance where I've found writing lots and lots of comments helpful is for functions with code that I'm writing for the first time. It's like rubber-duck troubleshooting - making myself explain what I'm doing in plain language actually helps me reason about it. I tend to leave those comments in because then the next person who works on it understands why I did something in a particular way. This perhaps results in superfluous comments, but you're never going to get it exactly right, and I think erring on the side of too many comments is probably better than too few.

interactivecode 5y ago
Are you familiar with Literate Programming? https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
- frereubu 5y ago
  Thanks for the pointer - I had read about it, but hadn't put two and two together. The kinds of things I work on (cacheable wesbites) don't need to be highly tuned for back-end performance, so I guess it's easier for me to do that.
  - masklinn 5y ago
    Lit style probably doesn't have much impact on performances, it's handled by the parser and mostly by ignoring the comments. It can impact the memory of runtime-oriented languages, especially if they keep the text around (e.g. for reflection or whatever) but that's about it.
cerved 5y ago
The problem with lots of comments is not primarily clutter, but as quoted from the article Writing and then maintaining comments is an expense. Your compiler doesn’t check your comments so there is no way to determine that comments are correct. You are, on the other hand, guaranteed that the computer is doing exactly what your code is telling it to. Unless your team has the discipline to maintain them, don't litter the code with comments. Put it in the commit message. Obsolete and incorrect comments are just confusing. What I sometimes do is write comments before I implement something. This provides a clear idea of what I need to do and where. Then when it's done I cut it into commit message or note
christophilus 5y ago
I do this in a markdown file, and then check that file into a /docs folder. That way, it doesn’t muddy the code, and even though it becomes inaccurate over time, it’s still handy for a “what was I thinking?” check.

interactivecode 5y ago

Are you familiar with Literate Programming? https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming

frereubu 5y ago
Thanks for the pointer - I had read about it, but hadn't put two and two together. The kinds of things I work on (cacheable wesbites) don't need to be highly tuned for back-end performance, so I guess it's easier for me to do that.
- masklinn 5y ago
  Lit style probably doesn't have much impact on performances, it's handled by the parser and mostly by ignoring the comments. It can impact the memory of runtime-oriented languages, especially if they keep the text around (e.g. for reflection or whatever) but that's about it.

cerved 5y ago

The problem with lots of comments is not primarily clutter, but as quoted from the article Writing and then maintaining comments is an expense. Your compiler doesn’t check your comments so there is no way to determine that comments are correct. You are, on the other hand, guaranteed that the computer is doing exactly what your code is telling it to. Unless your team has the discipline to maintain them, don't litter the code with comments. Put it in the commit message. Obsolete and incorrect comments are just confusing. What I sometimes do is write comments before I implement something. This provides a clear idea of what I need to do and where. Then when it's done I cut it into commit message or note

christophilus 5y ago

I do this in a markdown file, and then check that file into a /docs folder. That way, it doesn’t muddy the code, and even though it becomes inaccurate over time, it’s still handy for a “what was I thinking?” check.