Comments

In my experience, comments guidelines tend to be similar from one team to the next. One common theme is the desire to add more comments because everyone came across a situation where more comments would have been beneficial. In a module with many authors, in a team with some turnaround, this is common.

But what if the guideline is to comment everything? Everything, as in private properties, private methods... just about every declaration. Everything, including such declaration: private var cancellables = Set<AnyCancellable>() ?

Uncle Bob is clear; this is insane. Let's dive into why, though...

When you need to add comments to every parameter of every function, every public, internal and private property, it is impossible to write good comments all the time. Comments-writing fatigue kicks in quickly! The comments become an English-syntax version of the code. I bet it would be possible to write a script to achieve this...

My day-to-day is filled with such comments. Every day I see comments that do not answer the questions I have when reading other people's code. Obviously, when you have to write so many comments, you end up writing whatever you need to pass the PR review. And that's not helpful. What comment can you add to the cancellables property? I also believe the more useful comments are within a function's implementation; they justify a choice, or explain the code with the business rule.

Why is that guideline in place, you ask? In such a place that I could not dislodge it? Good question. The reasons I heard were like: I have "ocd-like symptoms" and like to see comments for everything (spoiler alert, that's not OCD, it's rigidity and fear of change). I also heard: otherwise, how will we know what to comment? And lastly: to avoid back-and-forths in PR reviews.

Well, liking uniformity is not OCD; coding guidelines can easily dictate what to comment on; we already have tons of back-and-forths about comments in PR reviews.

The solution

If we look instead at the purpose of comments, we can come up with a sane recommendation. We want to avoid confusion when reading any code that is not something we wrote last week.

I strongly believe good naming is key. But this concept goes beyond objective-c-length long names. It implies refactoring a non-trivial condition into a computed property, for example, to give a name to that condition. The same goes for small portions of functions that can be refactored into smaller functions. Stating the intention of the code with patterns, good practices and clear naming is all it takes.

I suggested only adding comments to public declarations and protocols.

Because in the end, comments lie. They become out-of-date in an instant. They also become something more you need to maintain. Reading comments instead of the code is a huge risk to misunderstand the code.