Writing system software: code comments. - <antirez>


33 bookmarks. First posted by tgecho 16 days ago.


“In this post I analyze Redis comments, trying to categorize them. Along the way I try to show why, in my opinion, writing comments is of paramount importance in order to produce good code, that is maintainable in the long run and understandable by others and by the authors during modifications and debugging activities.”
development  comments  opinion  site:antirez  author:antirez 
12 days ago by ryanq
Writing system software: code comments. - <antirez> <antirez> rss feed | twitter | google group | old site:
13 days ago by sshappell
For quite some time I’ve wanted to record a new video talking about code comments for my "writing system software" series on YouTube. However, after giving it some thought, I realized that the topic was better suited for a blog post, so here we are.
13 days ago by nateansel
Writing system software: code comments.
from twitter
13 days ago by RBaumier
A taxonomy of code comments.
code  design  programming  comments 
14 days ago by pw201
Writing system software: code comments
from twitter
14 days ago by nicola
In this post I analyze Redis comments, trying to categorize them. Along the way I try to show why, in my opinion, writing comments is of paramount importance in order to produce good code, that is maintainable in the long run and understandable by others and by the authors during modifications and debugging activities.

Not everybody thinks likewise. Many believe that comments are useless if the code is solid enough. The idea is that when everything is well designed, the code itself documents what the code is doing, hence code comments are superfluous. I disagree with that vision for two main reasons:

1. Many comments don't explain what the code is doing. They explain what you can't understand just from what the code does. Often this missing information is *why* the code is doing a certain action, or why it’s doing something that is clear instead of something else that would feel more natural.

2. While it is not generally useful to document, line by line, what the code is doing, because it is understandable just by reading it, a key goal in writing readable code is to lower the amount of effort and the number of details the reader should take into her or his head while reading some code. So comments can be, for me, a tool for lowering the cognitive load of the reader.
programming  maintenance 
15 days ago by austinpmaher
Writing system software: code comments. - <antirez> <antirez> rss feed | twitter | google group | old site:
from instapaper
16 days ago by tgecho