DaedTech

Stories about Software

By

Is There a Correct Way to Comment Your Code?

Editorial note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.  While you’re there, take a look at all of the visualizations and metrics that you can get about your codebase.

Given that I both consult and do a number of public things (like blogging), I field a lot of questions.  As a result, the subject of code comments comes up from time to time.  I’ll offer my take on the correct way to comment code.  But remember that I am a consultant, so I always have a knee-jerk response to say that it depends.

Before we get to my take, though, let’s go watch programmers do what we love to do on subjects like this: argue angrily.  On the subject of comments, programmers seem to fall roughly into two camps.  These include the “clean code needs no comments” camp and the “professionalism means commenting” camp.  To wit:

Chances are, if you need to comment then something needs to be refactored. If that which needs to be refactored is not under your control then the comment is warranted.

And then, on the other side:

If you’re seriously questioning the value of writing comments, then I’d have to include you in the group of “junior programmers,” too.  Comments are absolutely crucial.

Things would probably go downhill from there fast, except that people curate Stack Overflow against overt squabbling.

Splitting the Difference on Commenting

Whenever two sides entrench on a matter, diplomats of the community seek to find common ground.  When it comes to code comments, this generally takes the form of adages about expressing the why in comments.  For example, consider this pithy rule of thumb from the Stack Overflow thread.

Good programmers comment their code.

Great programmers tell you why a particular implementation was chosen.

Master programmers tell you why other implementations were not chosen.

Jeff Atwood has addressed this subject a few different times.

When you’ve rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand — when you can’t possibly imagine any conceivable way your code could be changed to become more straightforward and obvious — then, and only then, should you feel compelled to add a comment explaining what your code does.

Junior developers rely on comments to tell the story when they should be relying on the code to tell the story.

And so, as with any middle ground compromise, both entrenched sides have something to like (and hate).  Thus, you might say that whatever consensus exists among programmers, it leans toward a “correct way” that involves commenting about why.

The Main Problem with Comments

So far, I’ve offered adages and people’s opinions.  But I’ve done so without really diving into their underlying rationale.  In some cases, I couldn’t because they omitted it.  And, in other cases, I simply didn’t fit it into the quote.  Presumably, they all have their rationale.  But I’ll speak in broader terms here.

Comments have an obvious purpose: communication and clarity.  And they have an obvious downside: time spent writing them.  If the problem were simply a matter of weighing the time investment in commenting against the benefit in clarity, then they’d be something of a no-brainer.  But comments have a far more destructive downside.  On a long enough timeline, they often lie.

//Returns x + y or, if x or y is less than zero, throws an exception
public int Add(int x, int y)
{
    return x + y;
}

What happened here?  When you put on your code archaeology hat, you’ll probably conclude that a guard condition once existed.  Someone deleted that guard condition, but didn’t think to update the now-nonsensical comment.  Oops.

This hints at the inherent underlying problem.  Specifically, comments represent a non-compiled, non-enforced relationship between code and meta knowledge about code.  Adding comments adds cognitive maintenance burden for everyone that touches the code in the future.  And since nothing forces people to update the comments, they get out of sync.  This creates the possibility for negative returns on the effort of commenting.

Addressing the Burden of Comment Maintenance

At this point, I have yet to say anything controversial.  I think all parties can agree that commenting creates additional maintenance burden and seeks to pay for that burden with the clarity it provides.  Where people diverge, I suspect, has to do with the burden of the maintenance work.

Proponents of the code comment would argue that maintaining comments simply comes as part of maintaining code.  Opponents would counter that all such effort should go toward making the code itself clearer.  No comments, no comment maintenance burden, and no chance for comments to lie.

While I can see both perspectives, I’ll point out that only one lies counter to human nature.  Saying that all developers have a duty to comment places burden on people, some of whom will never accept that burden.  In doing this, you become the guy at the office demanding that everyone keep the single serving coffee pods in alphabetical order.  People won’t do it, and you will only achieve satisfaction by stamping your foot, getting angry, and haranguing people.

Even if you win, it would require draconian measures and result in resentment.  You might find yourself winning a Pyrrhic victory.  The people you badger have no natural incentive to comply with your demands.

A Main Heuristic for Commenting Code

Perhaps you can demand this high standard of professionalism.  And perhaps you find yourself in a like-minded group where this works.  But most likely, it just results in endless contention between you and others.  And, if you don’t execute the comment diligence flawlessly, the comments age poorly and have negative value.

As a result, I offer the heuristic that the correct way to comment is to avoid them as much as humanly possible.

Note now that I haven’t offered any sort of absolutes.  I haven’t said that you shouldn’t write comments.  Rather, I’m offering something a lot more nuanced.  The most likely outcome for a comment involves negative value on a long timeline, like playing games in a casino.  But I won’t tell you not to play blackjack and I won’t tell you not to comment.  I’ll just point out that minimizing these activities makes for a good life strategy.

So approach commenting skeptically.

Sometimes You Need Comments

That said, you do have situations that absolutely demand code comments.  For instance, some organizations have mandates for legal/copyright comments in each file.  By all means, add those comments when required.  (For this purpose, you might want to enlist a generator or something to avoid wasting your time.)

In addition you’ll want to add method header comments for the sake of documentation and Intellisense.  When you write code for consumption by others, these comments constitute de facto end user documentation.  In this situation, the value tends to outweigh the maintenance burden, since it impacts your product’s usability.

And, finally, sometimes you have something mind boggling in your code.  Sometimes you’ve refactored, cleaned up, and done everything humanly possible.  But you still have something that will confuse and stymie.  Far be it from me to say you shouldn’t explain with with a couple of slashes and some prose.  Do what you need to do.

But as you go, recognize comments for what they are.  They create a maintenance burden and have a negative expected outcome.  So use them cautiously, pick better options when you can, and understand that no amount of righteous indignation on your part will alter the human nature of others.

50 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Alain Van Hout
Alain Van Hout
6 years ago

Something that appears to be missing, and which in my experience tends to be the most common reason for (useful) comments: even with supposedly perfect code, life frequently gets in the way, in the form of arcane business requirements, quirky third-party libraries or misbehaving external intregration components. In those cases, comments immensely improve maintainability.

Ty Cahill
6 years ago
Reply to  Erik Dietrich

I can’t count how many junior programmers have had their minds blown when I’ve made them go through the jQuery library and read the comments and code. There’s a lot of really good comments in there…

Steve Sheldon
Steve Sheldon
6 years ago

In my experience the most relevant comments follow that saying about why other implementations were not choosen.

And that’s when you’ve tried something that should have worked based upon your reading of the manual, but it doesn’t. Like you find if you pass a parameter a certain way to a third party API the whole thing crashes. So you create a work around, some kind of check, or manipulating the call… and you add a comment so someone coming along later realizes that this was done on purpose and doesn’t accidentally refactor it out.

Brian O\'Callaghan
Brian O\'Callaghan
6 years ago
Reply to  Erik Dietrich

My own professional challenge right now: my predecessors wrote ugly, bizarre facades over perfectly straightforward third party APIs. Not to worry, the files *using the facades* are heavily commented about how to use the strange new interface.

Yay comments! /s

Sam
Sam
6 years ago

I think there is a big difference between one-line under 70 char comments and those multiline monsters. Any thoughts/styling guidance?

Jim Snyder
Jim Snyder
6 years ago
Reply to  Erik Dietrich

I appreciate you playing Devil’s Advocate, Eric. It would be impossible for my comments to get out of sync with the code as they are everything from business rules to process description. As an example, a query with “filter out unused X because it causes Y” is still meaningful even if “X” becomes unfiltered. Striping it out if the rules change would be preferable, but even if left, it provides some insight in the future.

Jim Snyder
Jim Snyder
6 years ago
Reply to  Sam

White space is free space. The compiler will strip them out, so the length should be according to what you need. I do not take pictures of my code, so functionality is all that matters.

Phil
6 years ago

//leaving a comment

Carlos Schults
6 years ago

I think one situation where it makes sense to comment is when you have a good reason not to follow a established best pratice or convention. For instance, let’s say your team agrees that a try-catch with no code in the catch block should not be allowed (which I think is a sensible rule to have). But then it happens that in this particular case you have a legitimate reason to do this “wrong” thing. In this case, I think you should add a comment explaining why you had to do this; otherwise, you risk a colleague removing your try-catch… Read more »

Randy Buchholz
Randy Buchholz
6 years ago
Reply to  Erik Dietrich

More worms in the can? 🙂 Once we open the discussion to constraints/artifacts outside of the code file the conversation changes. In this case, why would we create this test? Because of a Design variation. While there are good arguments for including test cases in the definition of design, it doesn’t solve the problem, it just relocates it. Where in the test case does the rational go? …in a Comment? Design decisions go in design documents, the design itself can include code and tests, but those aren’t the entire design. I’m in favor of comment by reference – if you… Read more »

Brian O\'Callaghan
Brian O\'Callaghan
6 years ago

I sometimes conceptualize comment problems as a subset of stringly-typed problems. Comments can lie, error messages can lie, parameterized switch statements can lie, user prompts can lie, etc.

Peter Muster
Peter Muster
6 years ago

If you have to maintain code written by others you already have the answer! I have worked with code that was many years old, programmed by people who left the company and every meaningful comment was very much appreciated. Comment on what the code is trying to achieve in business terms. Why things are done the way they are done (also why certain implementations were not chosen). The example “//Returns x + y …” is pretty useless when I can see that there is a calculation that adds x and y. Documenting your code and keeping up to date doesn’t… Read more »

simon C
simon C
6 years ago

I notice you said ‘ Why should I comment MY code’ – If you don’t you will be maintaining it forever !
Another good reason is Time, when you have been programming for 30+ years You wont remember why you did something in code – Its always useful to be able to re use an old algorithm or technique – or some weird interface spec.
Your old source listing is your documentation.
– Even if you re code it in one of todays here today, gone tomorrow languages , no one should have to reinvent the wheel.

My 2cents worth..

billy57
billy57
6 years ago
Reply to  simon C

That’s really true for me. I’ve always put some comment pages just in front of my shared code adding to the bare code some kind of history changes, guidelines, samples, tricks, … Nobody comes to me asking: “Why?”, “How to?”, “Can I?”, … I think also that, as the length of a program increases the use of comments becomes more and more mandatory. In my opinion I have not to legitimize my code writing comments that explain why I have NOT done this or that. My code is my code and it is obviously different from code written by anyone… Read more »

Jim Snyder
Jim Snyder
6 years ago

To me, commenting is self defense. I do not belong on either side of the religious war. I comment to help me maintain the code in the future. If half an hour of careful commenting saves me several hours of code reading when maintaining it, I win. As such, my comments rarely cover WHAT the code is doing, but rather WHY it was done that way and what the “gotchas” are. My assumption is that the code itself is self documenting, but the process is not.

Øyvind Hansen
Øyvind Hansen
6 years ago

1. Copy spesification into IDE
2. Comment text (add // before each line)
3. Start coding between comments

John Morrison
John Morrison
6 years ago
Reply to  Øyvind Hansen

I know that in some places this is supposed to be the correct procedure but only the most naive managers think that it can work and only the most cynical and depressed programmer is happy to work this way.

Jeff Jones
6 years ago

The code tells what. The comments tell why. If you have software developers writing code that will not be sufficiently thorough as to update existing comments when necessary, then either help them get to a professional level of performance, or get rid of them and hire developers who can perform in a professional manner. Some developers who think long term will use comments as a kind of pseudocode when initially developing the software inside the calluses they created. That allows them to think through what they are doing before writing code they will have to change. Leaving those comments in… Read more »

Jeff Jones
Jeff Jones
6 years ago
Reply to  Jeff Jones

classes, not calluses. 🙂

Jeff Jones
6 years ago
Reply to  Erik Dietrich

That approach is certainly a possibility (and I have seen that very thing happen) unless the team lead or software development manager doing the hiring addresses it during an interview, and has the communication skills to make the case. Not every experienced developer makes a good leader or manager.

Brad Eckert
Brad Eckert
6 years ago

This article has encouraged me to comment more.

“I think all parties can agree that commenting creates additional maintenance burden and seeks to pay for that burden with the clarity it provides.”

Uh, okay. Hours of coding versus seconds of commenting on the non-obvious aspects of the code. If you don’t like comments, don’t read them. If you don’t trust the comments, don’t believe them. If there are no comments, thank the previous programmer for your job security.

Les
Les
6 years ago

If you cannot describe what you did, why you did it and how the next person should look at it, you are not professional yet.
If you have worked on some of this “self documenting code” and tried to maintain it, then you should know better.

It is like the engineer that uses math to explain how something he designed works. In many cases the math obscures some important points that he or she did not understand themselves, and the math shows the same as the function, but neither shows how to troubleshoot or fix a failing piece.

Jeff Jones
6 years ago
Reply to  Erik Dietrich

As long as the external documentation is discoverable a year later by a new hire seeing the code for the first time. Inline comments or external – it makes no difference as long as it is usable short-term and long-term.

John Morrison
John Morrison
6 years ago

You definately need a comment if your code does something that can easily be misinterpreted.

if(p = q) //assignment folllowed by test

without the comment it likely to get ‘corrected’ to

if(p == q)

which would break the code

Brian O\'Callaghan
Brian O\'Callaghan
6 years ago
Reply to  John Morrison

Think about the history of how that comment got there in the first place. Someone writes “if(p = q)”. Then he realizes, “Oh! Someone might misinterpret the two-step assignment/test as a simple comparison…”. Which is a great realization. He now writes: if (p = q) //assignment folllowed by test or p = q; if (p) I’d rather he writes the latter. Because then more thoughts can continue flowing: “wait, I’m doing an assignment and I’m conditionally doing something based on a value. But prior to the assignment, I had all the information necessary to know which conditional branch I was… Read more »

Erik Dietrich
6 years ago

Wow, very well said! I was planning to respond in a similar vein of thinking, but you expressed that as well as I could possibly have.

John Morrison
John Morrison
6 years ago

Code comments should be added wherever the code might otherwise be misunderstood. Apart from that the most useful thing is a seperate document which is a narrative written in readable prose describing major design decisions and subsequent major design changes or refactorings. The main problem with reading and working with the code of others is complete disorientation.

Bot
Bot
6 years ago

This is all very theoretical. The acid test is code maintainability and that would require a study testing which structures, formats and styles of code are in actuality the most efficiently maintainable. Also, comments can have other key roles, such as the ‘special’ format of comments used by JavaDoc in NetBeans to describe the use of functions in the Intellisense – absolutely indispensable.

Erik Dietrich
6 years ago
Reply to  Bot

Definitely agreed about the style of comments you mention (though in my mental model, I categorize that as something else, namely “code documentation”).

CFS
CFS
6 years ago

As a lifetime consultant, I feel that comments are my billboard that highlight my work and can lead to future business.. Precisely explaining delivered code is important. Quick reference to specific areas of concern aid in understanding much like the TOC in a book that we evaluate for purchase or reference. Admittedly, most code nowadays is short but if commenting is avoided what about the technical documentation??

Taeyun Kim
Taeyun Kim
6 years ago

For programmers whose native language is something other than English (more seriously, not Indo-Europian one), comments written in their native language can be much more helpful, since their code is inevitably littered with ‘wrong’ variable and function names. Simply it’s hard to communicate only with the code itself – like communicating with a foreign language.

Ty Cahill
6 years ago

I’m currently tweaking a WordPress plugin, and if the original developer hadn’t added comments along the way I’d seriously consider hanging myself. He added a lot of really good comments, and I thoroughly appreciate it.

When someone new wants to step in and quickly change some code, comments can make it so much easier than digging through code to understand it. In this situation, I don’t need or want to understand the code–I just want to find where to make the necessary updates so I can move on with my day.

Ty Cahill
6 years ago

I think it’s funny how many COMMENTS have been added to this article. 🙂