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.

#programming #coding #softwaredeveloper


RELATED CONTENT

How Senior Programmers ACTUALLY Write Code
   • How Senior Programmers ACTUALLY Write...  


Need help with your career? Book a free career consultation:

https://jaymeedwards.com/services/sof...


CHAPTER MARKERS

00:00 Introduction
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


Download a free software development career guide from my home page:

https://jaymeedwards.com