Graham Cox

Posted on Mar 4, 2018

Self Documenting code isn't

I know this is going to be a very controversial article, but I'm going to write it anyway.

Self Documenting code is not a good goal to aim for. Quite the opposite in my opinion.

Comments in code exist for a number of reasons. One of those is to tell what code does, and this is the kind that Self Documenting code seeks to remove. This is not a bad goal, because if the code needs comments to tell you what it does then it's too complicated.

Another form of comment, though, is the one that tells you why code does what it does. This is much more important that what because this is not self evident from the code itself. This can come down to code design decisions, product design decisions, large scale architecture decisions, or a myriad of other reasons.

Yet another form of comment is links to external sources. This can be issue tracker numbers, design documents, or many other things.

Finally, sometimes you really do need to document the big picture of how something works, because the entire algorithm is complex and it's not feasible for everyone to read all of the code to get the big picture overview.

So, whilst striving to make your code clean, obvious and easy to follow, don't go to far in removing all code comments because they have other uses too.

Top comments (33)

Jason McCreary • Mar 5 '18

Developers often equate clean code to self documenting code to no comments. It's neither a zero-sum game, nor are all these things necessary conditions of one another.

As the author of many clean code articles as well as removing comments I think this is an important distinction. Otherwise these topics can become similar to the tabs vs spaces holy war.

I am obviously on the other side of the spectrum. I challenge myself to rework the code so what comments are no longer required. That doesn't mean my code doesn't have comments. There may be an occasional why comment. I just use them sparingly to keep the code my primary medium of communication.

Graham Cox • Mar 5 '18

And that, in my mind, is absolutely great. My problem is the case where people decide that they've reworked the code so that what style comments are unnecessary, and so they remove all comments - including the why style ones.

Patrice Gauthier • Apr 20 '18

I stand by this too. How often did we see old comments that lead you off the understanding of the code because it wasn't updated? To me if you have to write a comment saying what it does it's a code smell that needs refactoring. Too much comments is a noise that we all end up ignoring and then collects dust. I only write down a comment saying why some code is written in some way to explain it's unusual design and that it was (hopefully) the best idea at the moment. Only 2 rules of exception here for noisy comments : you write assembly or the comments are used by testing tools for test cases. Rare comments catch the eye.

Ben Halpern • Mar 5 '18

So the big argument for making code "self-documenting" is that comments and documentation can get out of date (and lie) and code cannot. But obviously there is no silver bullet and everything you are saying is also very valid.

Are there any languages or environments that enforce commenting and documentation accuracy in some way? Like a compiler that demanded comments be structured a certain way and enforced that they be manually timestamped for correctness if the code they referenced changed? Obviously no system is perfect, but we rely on other pseudo-accurate measures of correctness like testing itself.

Unai Esteibar • Mar 5 '18 • Edited

Elixir does this, you can check it out at hexdocs.pm/elixir/writing-document...

If you add

iex> MyApp.Hello.world(:john)
      :ok

in your function doc, and add the DocTest to your test suite, then this examples will run as tests. And yes, this comes built in in the language.

I have to say, it's really awesome checking out the docs for any given library and being confident that the code examples will just work.

Ben Halpern • Mar 5 '18

Really slick. Definitely seems like Elixir and Elm are two new languages going the extra mile to solve a lot of problems with functional programming while also making developers happy and sane.

Michael "notriddle" Howell • Mar 5 '18 • Edited

Anything with doctests. Unai Esteibar listed Elixir's exunit, and this is also a feature of Rust's rustdoc, and there are less-official ways to add it to other languages.

Like all automated testing systems, though, it's only a partial solution. The best comments I've ever seen tend to be things like this:

From a user's point of view, realm_view_pills_button looks exactly the same as realm_view_pills, and should never have any user-visible differences.

The reason we have both is that realm_view_pills_button is actually a bunch of buttons under the hood, and will completely rebuild the view and hit the network when you switch tab. You should use it if you expect more than five tabs. realm_view_pills, on the other hand, is actually a Bootstrap pills-tabs view under the hood, and allows the user to switch between them more quickly.

You try writing that kind of stuff in a way that gets automatically checked.

Thais Hamilton • Mar 7 '18

Clojure does not enforce, but you can comment what the function does like:

(defn give-me-motivation
  "Prints Rocky Balboa motivational phrase"
  []
  (println "Life's not about how hard of a hit you can give... it's about how many you can take, and still keep moving forward."))

Guillaume Martigny • Mar 5 '18

In the Javascript realm, I think jsDoc is a must !
It's easy to write, help with auto-completion and "bad parameter" check. If your editor knows how to read it (and it should), it catch a lot of spelling mistakes.

Adam Brandizzi • Jun 8 '18

As Michael noted and Unai exemplified with Elixir, there is this concept of doctests: code snippets with expected outputs to be inserted into documentation, executed and checked. I believe the first and most famous example is Python's doctest module, of which I'm a big fan :) and just got a nice post here in dev.to some days ago. I know there are third-party, somewhat experimental projects for other languages (such as many for JavaScript) but none very popular. Which is a shame, I have to say...

Tinus Smit • Mar 5 '18

Too often a project / class / method becomes way too cluttered with comments when following this idea of "commenting for the sake of commenting". Any developer worth his / her / their salt can follow a trail of code and infer the logic. You don't need comments to tell you "what" the code does. The code will tell you. Code has to update as requirements change. There's nothing beyond the developer's discipline that compels the developer to update the comments, thus they can't be (solely) relied upon.

I view comments in code (other than the Xml Documentation Comments) as a form of an apology to my future self / other developers. This links nicely to your "why" reasoning. I would have very specific reasons why the code is here / like this. Reasons vary from specific sequence of events to hacks to dealing with very niche scenarios encountered and accounted for. Comments in those instances stand out from the almost boilerplate nature of comments.

Comments linking to issue trackers and the like are not proper code comments, and should rather be check-in comments in your source control repository.

I wouldn't say don't write self-documenting code. I would actually say one should strive to do so. But use a few comments in cases where things aren't as obvious to the observer however many days / weeks / months into the future. And you'll find that people would actually pay heed to those comments, because of their rarity :-)

mnivoliez • Mar 6 '18

I totally agree with what you said. From my point of the view (and it may not be the good one) semantic is the key to everything. We write code for others, if we did for machines it should more look like assembly. The problem I got with comments is that often they are missused (at least in France, thanks to schools which ask to write comments everywhere even for saying it's an int). Most of the time, the code can express itself.
This is what I avoid:

// this function makes coffee
fn something() {
...}

This is what I strive for:

fn make_coffee() {
  ...
}

Same goes for parameters. In few words, don't do with comment what you can do with code. Instead use comment for what code cannot provide. For exemple the why as you said, but also exemple of the use, to explicit the chain of mind comming to this point. For exemple, some tools like rust documentation generator propose even the test as doc, test embedded in comment.

In short, too much comments kill the purpose of it. Like everything, it's a tool that should be use with care.

That's only my opinion and I may be wrong here.

Andrea Chiarelli • Mar 6 '18

Self documenting code should be developer's goal for many reasons. We have high level languages (high level because they are close to natural language): let's use them. Use comments where code is not enough (the why point is a good one).
I suggest:

write your code at your best
ask a colleague for proof reading
change your code accordingly

Tobias Salzmann • Mar 6 '18

Sadly, best practices/patterns/anti-patterns are often applied without understanding the problem they address.

And the solution seems to be similar in most cases: Understand why the best practice/pattern/anti-pattern is one, what the tradeoffs are and what that means for the specific case. Easier said than done, I admit.

In this case, There are some comments that are inherently important (why-comments) and some that are incidentally important (what-comments).
What I would prefer to do:

Refactor code into chunks that can be understood by reading names and type signatures.
Remove redundant comments
Keep the ones that still add value.

Eric Keyte • Mar 7 '18

I think you’ve hit the nail on the head. I worked on a team that disliked docblock comments (and would fail my code reviews if I included them). Their rationale was that any amount of commenting would allow a developer to become lazy when naming methods and variables, or wouldn’t extract functionality out. While I agreed on some level, the wholesale refusal to merge code that contained any comments at all seemed overkill. All too often I stumble across code that appears to be doing something odd, or a “better” solution is very obvious to me in that moment. In the rare cases that I’m able to discuss those past choices with the original developer, the reasons why are usually illluminating. Being able to communicate why something needs to be done seems like the best middle ground available, and is something that I try to be mindful of when I’m authoring or refactoring code. Good article.

Nicola Apicella • Mar 5 '18

There is no silver bullet and it's matter of trade offs like everything else, but generally speaking I think we should strive to write self documenting code.
Besides the obvious advantage of keeping in sync code and docs, self documenting code usually means code which is more modular, testable and reusable.

There are exceptions, for example like you mentioned, comments which explains the why some code does what it does.

There might be cases in which you also need do write comments to explain what the code does, but I really see it as an edge case, as a last resort.

One of those cases is when you write code which deals with microseconds latency. If I realize that adding a new class or new functions would cause a regression, then as a last resort I would write a comment.

Michael Ober • Mar 8 '18

Code can replace most "what comments" but it certainly cannot replace the "why comments". In addition, there are some "what comments" that are needed because they explain what a complex stretch of code does.

Brian Williams • May 7 '21

Yep exactly this!

Alain Van Hout • Mar 6 '18 • Edited

Most arguments against comments tend to implicitly assume that code can always also express why, despite the requirement to implement weird business rules being pretty much a/the staple of software development.

Jason C. McDonald • Mar 5 '18 • Edited

Agreed - comment why, not necessarily what. (Yes, the line blurs, but the point is for the comment to describe what you intended to happen, on a more human-thought level.) One way of approaching this is the Commenting Showing Intent standard.

Brian Williams • May 7 '21 • Edited

Comments are useful for explaining rationale but not much else.

If the code doesn't explain what it's doing then it's poorly written. Because most languages can be written in ways that are incredibly easy to read.

There seems to be an almost macho trend, especially in the FP world to try to write code that is demonstrably not readable and pretend like it is.

I hope that trend dies because its a nightmare.

zebmason • Mar 6 '18

ASCII art is a good use of comments, e.g. drawing a hidden-line diagram of a cube with the corner and mid-side node numbers since for FEA programs there are at least 3 different conventions. Typically this will be for processing by Doxygen.

dmcdivitt • Mar 6 '18

Code is written for other developers to read. If they can't read and understand code, they should not have the job. Code should always be self documenting by use of variable names, anyway. That should be stressed. Your verbiage does not do that. Of course, a comment can be added when necessary for unusually complex code, but most of the time is not needed.

Most people do not document. Are you going to be a moralist or a computer programmer. To obtain at least some documentation, stress and require self documentation.