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

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. You can also watch this episode on YouTube.  Get free access to TechRolepedia here:  https://jaymeedwards.com/access-techrolepedia/ Download my free Career Guide here:  https://jaymeedwards.com/developer-career-guide/ Need help with your career? Learn about career coaching:  https://jaymeedwards.com/services/software-development-coaching/ Chapter markers / timelinks:  02:50 Why Practice "Self-Documenting" Code? 02:56 #1 Laziness 04:43 #2 Reduce Visual Clutter 05:43 #3 Refactoring Burden 06:39 #4 Overconfidence in Simplicity 07:56 6 Benefits to Commenting 08:03 #1 Reduce Comprehension Effort 08:50 #2 Accelerate Business Understanding 09:50 #3 Use Comment Features in Editor 11:03 #4 Surface Code Behavior 12:07 #5 Additional Documentation Opportunities 12:48 #6 Treat Code Like a Product 13:51 Episode Groove Visit me at JaymeEdwards.com Find me on Facebook at JaymeEdwardsMedia Find me on Twitter as @jaymeedwards