Over a million developers have joined DZone.

Comments on Code Comments

David Bernstein has no idea how the debate on code comments is still going on because believes that code comments are bad - period.

· DevOps Zone

Discover how to optimize your DevOps workflows with our cloud-based automated testing infrastructure, brought to you in partnership with Sauce Labs

I have been accused in the past of encouraging developers to write uncommented code and this is true, but not because I don’t care about maintainability. On the contrary, I care about maintainability a great deal and that’s exactly why I encourage developers to think twice before they write a comment in their code.

Commenting code sounds like a good idea but it can encourage poor programming habits. Developers are less inclined to use meaningful names for behaviors or make their code expressive because it’s explained in the comments. But comments are not code and comments and the code they’re describing can easily get out of sync with each other. Efforts to keep them in sync are actually quite expensive, so commenting code can quickly become a liability. We want to be careful not to assume this additional cost unless it’s absolutely necessary.

The software itself is by far the best medium to express what it’s doing. We should strive to write software that’s clear and understandable because software needs to be maintained.

In scriptwriting, it’s often considered a bad device to use a narrator to explain a scene. Exposition is boring and it’s the sign of poor storytelling. The same is true in code. Our primary focus as software developers should be communicating in our code. We want to communicate what our design is while hiding as much as possible as to how that design is implemented. We want our code to be encapsulated with strong contracts so they are straightforward to understand and maintain.

There is an art and a science to this but unfortunately, I don’t often see it taught in school. Some of my clients have me train all their developers, including their new hires who are fresh from school. New hires in my classes often laugh when they hear my comments on comments because oftentimes their professors have drilled into them that they should have a comment for every line of code and that you should always explain what you’re doing in a comment.

This is not considered an industry best practice. Maybe these practices work when you’re building a simple software project like the kind you do within a semester in college, but not when you’re building enterprise software. Large projects require discipline and they also require a certain level of knowledge from the people who are writing and maintaining the code.

I expect the people who read my code in the future will understand the basics of software development. I shouldn’t have to explain what my code is doing. If I feel that I have to, then I should rewrite my code so it’s easier to understand. Of course, there have been times that I had to break this rule due to other considerations such as performance, availability, security, etc. Other considerations aside, I try to avoid comments and I discourage other developers from adding comments that explain what their code does.

However, there is a class of comments that are important to include in code and I’ll discuss those comments in next week’s post.

Download “The DevOps Journey - From Waterfall to Continuous Delivery” to learn learn about the importance of integrating automated testing into the DevOps workflow, brought to you in partnership with Sauce Labs.

Topics:
programming ,code commenting ,code comments ,clean code

Published at DZone with permission of David Bernstein, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}