If Code is Self-Documenting, Why Do Comments Exist?

Thriving Technologist

As programmers, we often follow practices because of hidden desires - and "self-documenting code" is chief among them. In this episode I'd like to share some of the tradeoffs and implications of choosing to add comments to your code or not, to help you make the best decision for your software development career.

When I first started developing software 25 years ago, the company I worked at mostly used C++ with a little Visual Basic and Java. At that time, all the other software engineers I worked with added comments to their code. And at the next two software product companies I worked for, programmers also chose to add source code comments as a regular practice.

But once I moved to Austin, Texas 15 years ago and got my first job as an IT consultant I noticed something interesting. None of the other programmers on my team added ANY comments to their code! When I asked them about this, they would often say "the client is paying for features, not comments". I didn't find this a very acceptable reason for not adding comments to code, but I did my best to play along.

Around this time the popular programming practice of "self-documenting code" first showed up on my radar. The idea being if we write our code with a clear enough intent, but using business terms and clean designs for the software we write, comments are unnecessary. But upon closer inspection I found this to be (in my opinion) wishful thinking rooted in laziness, upon a host of other factors.

I hope this episode helps you make an informed decision about whether the benefits of code comments are worth writing them, or whether you should continue to practice self-documenting code as a principle. I believe we can have the best of both worlds: well-written code that reflects the business domain and is simpler to read, but with accompanying comments to reduce the time it takes for our software development team to use the APIs, helper classes, and other functionality our code and libraries provide.

Join my Patreon: https://thrivingtechnologist.com/patreon

Learn about one-on-one career coaching with me: https://thrivingtechnologist.com/coaching

TechRolepedia, a wiki about the top 25 roles in tech: https://thrivingtechnologist.com/techroles

The Thriving Technologist career guide: https://thrivingtechnologist.com/guide

You can also watch this episode on YouTube.

Chapter markers / timelinks:

(00:00) Introduction (02:50) 1. Why Practice "Self-Documenting" Code?(02:56) 1.1 Laziness(04:43) 1.2 Reduce Visual Clutter(05:43) 1.3 Refactoring Burden(06:39) 1.4 Overconfidence in Simplicity(07:56) 2. 6 Benefits to Commenting(08:03) 2.1 Reduce Comprehension Effort(08:50) 2.2 Accelerate Business Understanding(09:50) 2.3 Use Comment Features in Editor(11:03) 2.4 Surface Code Behavior(12:07) 2.5 Additional Documentation Opportunities(12:48) 2.6 Treat Code Like a Product(13:51) Episode Groove

Visit me at thrivingtechnologist.com