Contact Us
Magenic
  • What We Do
  • How We Do It
  • Our Thinking
  • Join Us
  • Our Work
  • Industries
  • Cloud
  • Software Development
  • Quality Engineering
  • DevOps
  • Strategy
  • Experience Design
  • Data & Integration
  • Advisory Services
  • Careers
  • Culture
  • Events
  • Success Stories
  • Partnerships
  • Technologies
  • Professional Services
  • Financial Services
  • Retail
  • Health Care

A Case Against Comments

April 17, 2015 // By David Donahue

Want to hear something opinionated? Comments are a code smell. There, I said it. And I don't apologize for it.

All comments? Well, maybe not necessarily. I'll concede that there are exceptions to the rule. Header comments which drive intellisense can be useful, for example. Though, seriously, they don't need to be on everything. I'll also concede that once in a while there's an exception to the rule where the purpose behind a particular implementation could require a little more explanation. Comments like, "We use the magic value 3 here because Vendor X's product requires that. Don't let this magic value leak from this dependency implementation." for example.

But by and large nearly all of the comments I see in real-world code are a code smell. Why? Because they don't add value. They take up space (not as a measure of bytes in the file, but as a measure of time spent understanding and supporting the code), they clutter the code, and they offer no information that the code shouldn't already have.

I can already hear the responses from every manager, owner, alleged developer, etc... "But without comments how will we know what the code is doing?" As usual, someone else has said it better than I can:

Kevlin Henney Tweet

That's the gist of it, really. If a developer on the team isn't able to convey the business logic in a structured and meaningful way, what good are that developer's comments going to be? Does that developer even understand what he or she is writing? If not, aren't those comments just going to add more confusion and misinformation?

Robert Martin has been known to say, "Every comment is an apology." That apology is basically the developer saying that he or she wasn't able to express the meaning in the code, so he or she gave up and just wrote the meaning in comments instead. It's just that… giving up.

My own take on it is, "Every comment is a lie waiting to happen." That is, either the comment is saying something that the code isn't saying (so it's lying) or the code is going to change at some point and invalidate what the comment is saying (so it will be lying).

Think of it this way…

When you're reading code with lots of comments, do both the code and the comments unambiguously tell the same story?

If not, which one tells the correct story? Which one should tell the correct story? And why should the incorrect story also be told?

If they do both unambiguously tell the same story, then why does that story need to be told twice? Doesn't that violate DRY? What happens when one of their stories changes? Will the other change in the exact same way?

The story need only be told once. Tell it in the code.

David Donahue is a Lead Consultant at Magenic. This is republished from his blog and can be found here. To learn about custom application development from Magenic, contact us or give us a call at 877-277-1044.

Categories // Software Development
Tags Comments
SHARE:
THE LATEST:
  • FEBRUARY 23, 2021 // blog
    Stronger Product Owner = Better Software, Faster
  • FEBRUARY 19, 2021 // blog
    Security In Five Bi-Weekly Roundup – 2/19/21
  • FEBRUARY 18, 2021 // blog
    Doesn’t Everybody Know This?
Featured Content:
  • JANUARY 25, 2021 // White Paper
    The Top 7 Technology Trends of 2021

Related Posts

Blog
The Value of Code Reviews
Learn More
Blog
5 Things You Need To Know About Microsoft .NET 5
Learn More
Blog
Modernizing .NET Applications
Learn More
Blog
Mocking Injected Types in Blazor
Learn More

Ready to speak with our experts?

Have a question?

This field is required
This field is required
This field is required
This field is required

Thanks for Contacting Magenic

One of our experts will be contacting you directly within the next business day.

Return To Home
Magenic

info@magenic.com+1.877.277.1044

  • Facebook
  • Twitter
  • LinkedIn
  • YouTube
  • RSS Feed

© Magenic Inc.Privacy NoticeTerms & ConditionsSitemap