# Writing system software: code comments.

DevFeed: [Writing system software: code comments.](<https://devfeed.tech/articles/writing-system-software-code-comments-20615.md>)

Original publisher: [Read original article](<http://antirez.com/news/124>)

Published: 2018-10-06T20:08:58Z

Content type: opinion

Language: en

Sources: [Antirez](<https://devfeed.tech/sources/antirez.md>)

Topics: [Code](<https://devfeed.tech/topics/code.md>), [Redis](<https://devfeed.tech/topics/redis.md>), [debugging](<https://devfeed.tech/topics/debugging.md>), [Lua](<https://devfeed.tech/topics/lua.md>)

Tags: [code](<https://devfeed.tech/tags/code.md>), [code-comments](<https://devfeed.tech/tags/code-comments.md>), [cognitive-load](<https://devfeed.tech/tags/cognitive-load.md>), [debugging](<https://devfeed.tech/tags/debugging.md>), [opinion](<https://devfeed.tech/tags/opinion.md>), [redis](<https://devfeed.tech/tags/redis.md>)

## AI overview

The article analyzes comments in the Redis source code and argues that comments are important for maintainability, debugging, and understanding code. It emphasizes that comments can explain why code takes a particular approach and reduce the cognitive load on readers.

## Source excerpt

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. 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. The following code snippet is a good example of the second point above. Note that all the code snippets in this blog post are obtained from the Redis source code. Every code snipped is presented prefixed by the file name it was extracted from. The branch used is the current "unstable" with hash 32e0d237. scripting.c: /* Initial Stack: array */ lua_getglobal(lua,"table"); lua_pushstring(lua,"sort"); lua_gettable(lua,-2); /* Stack: array, table, table.sort */