DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Comments in Clean Code? Think Documentation

When you need to convey information about code to developers, make your code clean. When it's for the business, use documentation. Code comments work for none.

Erik Dietrich user avatar by
Erik Dietrich
CORE ·
Feb. 13, 17 · Opinion
Like (11)
Save
Tweet
Share
12.47K Views

Join the DZone community and get the full member experience.

Join For Free

Notwithstanding some oddball calculator and hobby PC hacking, my first serious programming experience came in college. A course called “Intro to C++” got us acquainted with arrays, loops, data structures, and the like. Given its introductory nature, this class did not pose a particularly serious challenge (that would come later). So, with all of the maturity generally possessed by 18-year-olds, we had a bit of fun.

I recall contests to see how much application logic we could jam into the loop conditions, and contests to see how much code could be packed onto one line. These sorts of scavenger hunt activities obviously produced dense, illegible code. But then, that was kind of the point.

Beyond these silly hijinks, however, a culture of code illegibility permeated this (and, I would learn later) other campuses. Professors nominally encouraged code readability. After all, such comments facilitated partial credit in the event of a half-baked homework submission. But, even still, the mystique of the ingenious, but inscrutable, algorithm pervaded the culture both for students and faculty. I had occasion to see code written by various professors, and I noticed no comments that I can recall.

Professionalism via Thoroughness

When I graduated from college, I carried this culture with me, but not for long. I took a job where I spent most of my days working on driver and kernel module programming. There, I noticed that the grizzled veterans to whom I looked up meticulously documented their code. Above each function sat a neat, orderly comment containing information about its purpose, parameters, return values, and modification history.

This, I realized, was how professionals conducted themselves. I was hooked. Fresh out of college, and looking to impress the world, I sought to distinguish myself from my undisciplined student ways. This decision ushered in a period of many years in which I documented my code with near religious fervor.

Image title

My habit included, obviously, the method headers that I emulated. But on top of that, I added class headers and regularly peppered my code with line comments that offered such wisdom as, “increment the loop counter until the end of the array.” (Okay, probably not that bad, but you get the idea). I also wrote lengthy readme documents for posterity and maintenance programmers alike. My professionalism knew no bounds.

Clean Code as Plot Twist

Eventually, I moved on from that job but carried my habits with me. I wrote different code for different purposes in different domains but stayed consistent in my commenting diligence. This I wore as a badge of pride.

While I was growing in my career, I started to draw inspiration from the clean code movement. I began to write unit tests, I practiced the SOLID principles, I watched Uncle Bob talks, made my methods small, and sought to convince others to do the same. Through it all, I continued to write comments.

But then something disconcerting happened. In the clean code circles I followed and aspired to, I started to see posts like this one. In it, the author had written extensively about comments as a something to avoid.

Comments are a great example of something that seems like a Good Thing, but turn out to cause more harm than good.

For a while, I dismissed this heresy as an exception to the general right-thinking of the clean code movement. I ignored it. But it nagged at me nonetheless, and eventually, I had to confront it.

When I finally did, I realized that I had continued to double down on a practice simply because I had done it for so long. In other words, the extensive commenting represented a ritual of diligence rather than something in which I genuinely saw value.

Down with Comments

Once the floodgates had opened, I did an about-face. I completely stopped writing comments of any sort whatsoever, unless it was part of the standard of the group I was working with.

The clean coder rationale flooded over me and made sense. Instead of writing inline comments, make the code self-documenting. Instead of comments in general, write unit and acceptance tests that describe the desired behaviors. If you need to explain in English what your code does, you have failed to explain with your code.

Probably most compelling of all, though, was the tendency that I’d noticed for comments to rot. I cannot begin to estimate how many times I dutifully wrote comments about a method, only to return a year later and see that the method had been changed while the comments had not. My once-helpful comments now lied to anyone reading them, making me look either negligent or like an idiot. Comments represented a duplication of knowledge, and duplication of knowledge did what it always does: gets out of sync.

My commenting days were over.

Best of All Worlds

That still holds true to this day. I do not comment my code in the traditional sense. Instead, I write copious amounts of unit, integration, and acceptance tests to demonstrate intent. And, where necessary and valuable, I generate documentation.

Let’s not confuse documentation and commenting. Commenting code targets maintenance programmers and team members as the intended audience. Documenting, on the other hand, targets external consumers. For instance, if I maintained a library at a large organization, and other teams used that library, they would be external consumers rather than team members. In effect, they constitute customers.

If we think of API consumers as customers, then generating examples and documentation becomes critically important. In a sense, this activity is the equivalent of designing an intuitive interface for end-users of a GUI application. They need to understand how to quickly and effectively make the most of what you offer.

So if you’re like me — if you believe firmly in the tenets of the clean code movement — understand that comments and documentation are not the same things. Also, understand that documentation has real business value and occupies an important role in what we do. Documentation may take the form of actual help documents, files, or XML-doc style comments that appear in Intellisense implementations.

To achieve the best of all worlds, avoid duplication. Make publishing documentation and examples a part of your process and, better yet, automate these activities. Your code will stay clean and maintainable and your API users will be well-informed and empowered to use your code.

code style Documentation

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

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • Better Performance and Security by Monitoring Logs, Metrics, and More
  • Differences Between Site Reliability Engineer vs. Software Engineer vs. Cloud Engineer vs. DevOps Engineer
  • Kubernetes vs Docker: Differences Explained
  • How To Check Docker Images for Vulnerabilities

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: