There’s a constant discussion in programming about the use of comments. A great Swift blogger and book author, Erica Sadun, wrote a lot about comments in the past.
Recently, Andrew Warner wrote an article saying that writing comments in code is often obsolete, and even harmful to your codebase.
Comments decay. They aren’t compiled, and they’ll never get executed at runtime. If they become out of date or incorrect, no test is going to fail and no user is going to complain. Programmers work around them out of fear that “somebody might need this comment or it might provide some value in the future”, pushing them along far after they’re useful (if you can even argue that they were useful in the first place).
Erica wrote a great response to the article, stressing the importance of comments in your code base.
Comments don’t just paper over bad design and coding. They document a process of making code right, supporting future reading and modification. Good comments reduce the mental effort needed by readers each time they review your source, enabling them to focus more on specific tasks like “howto I add this feature” rather than “what the hell was going on here”.
I agree completely with Erica, and I wanted to stress one particular way in which comments help the readers of your code.
In the past, I worked mostly with a senior developer much smarter than me, and we had almost no comments in our code. We are experienced with iOS and we usually don’t work on the same file. Because of this, we didn’t run into code readability issues often.
However, in our most recent project we brought in a new hire, a savvy Java developer still learning Swift and iOS. This is the first time I noticed our code is fairly unreadable at times.
Doing pair programming and seeing him go trough our codebase, I could see he had difficulties discerning what was part of Swift or iOS, and what was our code. It also seemed like he could easily understand a method and what it does, but had trouble seeing how all the pieces fit together.
This is especially true with more complex code in a *UIViewController. *Because of the nature of UI code, different pieces like animations, lifecycle methods, styling and presentation are all mixed together and are mutually dependant.
This is where I noticed our adage of “comments are only for bad code” fell apart. Reading code is hard, not matter how good the code is. Figuring out how all of these different pieces fit together is not an easy task. It’s our job, as developers, to make reading code easier.
When writing articles, I always pay special attention to the intro I’m going to write. Its purpose is to establish context and motivation for the reader to understand what to look for in the article.
If you read an article without the first few paragraphs, you will have to spend the first few minutes trying to discern what this article’s purpose is. Is it a tutorial? Is it a news article? Is it an ad?
During those few first paragraphs, you focus your attention on trying to parse the article itself instead of the actual content. You also don’t have the context necessary to understand what the article is trying to say.
An article is more than the sum of its paragraphs. The way those paragraphs flow and fit together establishes a common thread and achieves the purpose you want to achieve.
The same goes for code. A class is more than the sum of its public methods. Each class has responsibilities (a point) and fits in together with the code around it (a context). Try as we may, usage of classes will always impact the way we write them. No method is completely isolated from the call-site. Each class has a context it fits within.
When reading code, without having the context of what a class does, you have to read trough it a couple of times to figure out the dependencies within it, and how it all fits together. Just like an article without an intro, this wastes time for the reader, and can lead to bugs when other developers (or future-you) try to change something.
This is why I would definitely suggest a big comment block over each class (or complex method) that describes, in essence, what the purpose of that code is. Each piece of text needs an intro, why would a class be any different?
Always remember that code is read much more than it’s written. Optimise for the reader, not the writer.