Maybe I’m Over Commenting Code (Are You?)

A couple of weeks ago, I was talking with a friend and a fellow developer about code, clarity, and generally over commenting code (how meta, I know).

The following statement was made about some of the code I write – and before I share it, I take no offense to this whatsoever. I dig these kind of discussions between peers.

Truth be told, I kind of agree with it.

I’m definitely less comment-y than you

When it comes to commenting code, I’m pretty verbose. This means I try to DocBlock everything from the server-side code to the the JavaScript and even add code blocks to my Sass (or even vanilla CSS) code.

Furthermore, I’ll comment on blocks of code that are used throughout my functions even though they may be only, say, 15 – 20 lines long.

This used to be something I constantly debated about myself, but I’ve stopped with it and accepted this is how I write code.

Over Commenting Code

There are tons of articles, books, talks and so on talking about how code should look, how long methods should be, how testable the code should be, and so on and so on.

Overcommenting

All of the above is important. It’s not always presented in the most interesting way, but I believe that it’s part of what we, as programmers, should be familiar with regarding the that we write.

But when it comes to comment, there seems to be a handful of ways people think we should comment our code:

  1. Let the code be the documentation,
  2. Comment only what’s necessary, such as classes and functions and blocks that may be difficult to understand,
  3. Or comment frequently.

Personally, I sit between the second and third opinions leaning more in the direction of the third.

Here’s why: Over the years, I’ve found no matter how clear I try to write by code – using clear function names, variable names, certain types of notation, and so on – it’s still code.

  • a system of words, letters, figures, or other symbols substituted for other words, letters, etc., especially for the purposes of secrecy.
  • program instructions.

By its very nature, it’s something that’s uses symbols to achieve its purpose.

An Ultimate Goal?

We should write code that’s easy to follow. We should write meaningful class names, variable names, and class names. The relationship between all of the parts of the program from the front-end to the back-end should be clear (well, as clear as they can be).

But we’re still writing code.

And months – let alone years – when we have to revisit part of a program we and/or a team of people worked on, I’d rather have a few sentences of comments explaining what’s supposed to be happening rather than spending time re-familiarizing myself it and trying to debug and step through what others did to make sense of what it’s currently doing versus what it’s should be doing.

I know – it’s not really a popular way to write code. At this point in my career, that’s completely cool with me. I’ve accepted it. When it comes to revisiting a project in the future, I’ve never regretted it.

17 Replies to “Maybe I’m Over Commenting Code (Are You?)”

  1. So glad you’re all for commenting as much as possible. Definitely helpful for those sleepy mornings or “what the hell was Rachel from 6 months ago thinking when she wrote this” moments. :-) I also find that when I comment code, I’m sort of re-iterating the steps happening to make something function. If I can’t do that clearly in comments, then that is a red flag to stop, and figure out why I don’t understand something as well as I thought I did.

    1. I also find that when I comment code, I’m sort of re-iterating the steps happening to make something function.

      Right – and it also helps to give an idea as to if code should be refactored or not.

      If I can’t do that clearly in comments, then that is a red flag to stop, and figure out why I don’t understand something as well as I thought I did.

      Agreed – this is a good thought.

  2. I hear you, Tom. Keep on preaching it!

    The bane of my professional existence is being handed systems to support which were written by lone-wolf developers (who are no longer available when I inherited the code), who knew exactly what THEY were doing and had no interest in anything beyond making their clients smile TODAY. Terms like ‘future’, ‘team’, ‘best practice’ and ‘support’ just weren’t part of the vocabulary.

    I get it that many devs are in environments where various pressures force them to work like this, but a large number of them will tell you that they signed on to write code, not English. For a variety of reasons, they simply won’t do any more internal documentation than they themselves need (which is often nearly nothing…until they turn 40). Consequently, their successors pay in frustration and delay. Apparently, some of these guys only CREATE systems and never have to support or reverse-engineer something somebody else built.

    At the very least, every class, method and function needs a minimal DocBlock with at least a parameter list. I don’t think requiring a single line describing the object’s operation is too much to ask. Just this one thing would do wonders for everybody downstream, particularly if they are using an IDE.

    1. Terms like ‘future’, ‘team’, ‘best practice’ and ‘support’ just weren’t part of the vocabulary.

      I’d say that even today, those terms are used and abused. They are important, they are meaningful, but they are also tossed around in such a way that it makes it difficult to take it seriously, sometimes.

      Anyway, I know what you’re saying though, and you’re right.

      At the very least, every class, method and function needs a minimal DocBlock with at least a parameter list. I don’t think requiring a single line describing the object’s operation is too much to ask. Just this one thing would do wonders for everybody downstream, particularly if they are using an IDE.

      +1

  3. Agreed 100%! My boss even commented his frustration once about my need to comment and document but months later he was praising the fact that even with his limited code comprehension he could make changes and understand my work. This has removed fears of collaborating and growing our team because not only is our codebase clear but coding standards are clear and anything outside of that becomes an immediate eye sore.

    The drive for this comes from so many experiences of digging for countless hours through another developers work for the simplest of answers. Even when I hire, I hire for character, because the only people unwilling to properly comment are stubborn, naive, and prideful to think their code is perfect as is and will never be revisited, seen by someone else, or used in other instances.

    Rant over, couldn’t agree more with today’s PSA.

    1. …months later he was praising the fact that even with his limited code comprehension he could make changes and understand my work.

      +1. Love that.

      The drive for this comes from so many experiences of digging for countless hours through another developers work for the simplest of answers.

      Right. And it’s not limited to other people’s code either, but when others have to work with my code, you know?

  4. More than code comments, it’s code clarity that’s most important.

    And code comments are no substitute for solid documentation. I think too often coders write muddy code and compound the issue with poor docs. Code comments won’t help that situation.

    Sure, add a header comment to classes/functions/methods. The odd in-depth illumination is helpful in strange cases, but let’s be a little more verbose instead of convoluted in complexity, and devote all other energy to great docs.

    Frankly, I’ve chosen libraries based on their good docs because often the code contained functionality that was not even documented. That’s not uncommon. And I shouldn’t have to read the code to discover functionality and correct usage.

    WordPress has always done well off good docs (although there are still some puzzling holes). Codeigniter lasted longer than it should have due to good docs. Laravel’s success is partly due to its great docs and very clear code.

    1. More than code comments, it’s code clarity that’s most important.

      I agree – I think meaningful variable names, class names, and function names are all important. Making sure that the flow of control reads as close to a natural flow as possible is something we should ultimately aim for.

      But we’re also still writing code, so I think that sometimes we think we’ve written really clear code when, in a few years, we come back to it and it’s not as well-written as we originally thought. Either we’ve learned more, gotten better at writing more, or simply didn’t do as good a job as producing it as expected in the first place.

      And I shouldn’t have to read the code to discover functionality and correct usage.

      Yes – I think code comments should compliment the code, not completely explicate what we’re seeing.

  5. It depends on what you write in a comment. Comments should explain why something was written this way and maybe what the side-effects are.

    If your code just says what happens in the code it is either redundant (and makes the code harder to read), or your code isn’t good enough.

    In you sample screenshot, you have a function that does way too much. It is a combination of unrelated validators that should go to separate classes/methods with meaningful names, and you are returning the same value for very different exit reasons. Comments cannot fix–or compensate for–that.

    I like good comments. But whenever I feel the need for a long comment, I know I’m missing a refactoring opportunity.

    1. It depends on what you write in a comment. Comments should explain why something was written this way and maybe what the side-effects are.

      Agreed; this is a really good, succinct way to put it.

      In you sample screenshot, you have a function that does way too much.

      I don’t disagree – it’s funny, though: I quickly snapped a screenshot of a project that was in development not thinking that that many people would examine it, but I got just about as many comments via Twitter as I did about the screenshot alone :).

      There’s content for a whole other post on breaking functions up in situations like this, but I digress for now. Thanks for bringing this up, though – it’s useful to have as a reminder and as for those who may be reading these comments after the post.

      I like good comments. But whenever I feel the need for a long comment, I know I’m missing a refactoring opportunity.

      This is another good rule of thumb. +1.

  6. I’m curious, do you stop and add a lot of comments while you’re writing the code, or do you go back and add them in afterwards?

    I’m becoming “more comment-y”, but it largely depends on the purpose of the code I’m creating. I always try to leave an inline comment if there’s something tricky, but with code I’m releasing to others I’m trying to be more thorough. Maybe to the point of over explaining at times, when I’m thinking about someone learning to code looking at it in the future. While I don’t like reading comment-heavy code as much, there’s certainly no harm in it.

    You’ll have people tell you with absolute certainty that more comments are better, and other people just as certain tell you the code should be self-documenting. As though there are these rules that “real” developers follow, when mostly there’s only people that think they know best because that in turn means they must be a better developer for doing it that way. If you can’t benchmark it and show me a certain way is the most performant, then it’s your opinion. And even then, sometimes it’s better to take the slightly less performant path (or verbose when it comes to comments) because it better achieves the goals for the project instead of checking off an imaginary list of things that make you a good enough developer that other developers will stop telling you that you’re doing it wrong.

    We do a disservice to growing developers (and even experienced ones) when we make every single thing so clear cut as right or wrong. Different tools and techniques for different situations. When we focus on simply telling people they’re doing it wrong and they should do it our way all the time we risk stunting their development and ruining their confidence, when the sites/apps/software they produce very well might work just as well as our own even if they did it differently. I very much respect that you keep an open mind on your blog and try to foster that along with growth in skills in your readers.

    1. do you stop and add a lot of comments while you’re writing the code, or do you go back and add them in afterwards?

      I generally comment as I go as it helps be to think through the logic that my code is doing. Sometimes, when trying to explain it in English, I end up realizing I’ve missed a case or the code could be clearer either through the use (or removal) or a variable or addition of a function or something like that.

      I always try to leave an inline comment if there’s something tricky, but with code I’m releasing to others I’m trying to be more thorough.

      The way I see it: If the code can be understood without a comment, then I’ll try to leave out a comment (maybe an inline comment is necessary, I don’t know). Otherwise, I’ll comment because even if I’m the only one who will revisit the code in the future, I want to know what I was thinking and what the code is supposed to be doing.

      You’ll have people tell you with absolute certainty that more comments are better, and other people just as certain tell you the code should be self-documenting. As though there are these rules that “real” developers follow, when mostly there’s only people that think they know best because that in turn means they must be a better developer for doing it that way.

      Yep — this is one of those things that can bite you early in your career, but you ultimately have to decide what works best for you and just roll with it.

      When we focus on simply telling people they’re doing it wrong and they should do it our way all the time we risk stunting their development and ruining their confidence,…

      Very well said, and I agree.

      I very much respect that you keep an open mind on your blog and try to foster that along with growth in skills in your readers.

      Thanks – I appreciate that!

  7. I comment heavily, even if it is redundant. I feel like writing something in plain English helps clarify things and helps step through the process.

    I don’t just comment what the code is doing, but WHY it was decided to do it that way.

    Sometimes there’s a conversation that takes place and it’s decided to implement something a certain way, and whether it makes sense at the moment or not, I find that coming back 6-months later to my own code, or if I’m working on someone else’s code, I tend to question why things were done a certain way. If there’s a comment explaining the reasoning as well as the functionality of the code, I know to either leave it as-is to satisfy some sort of previous reasoning/requirement, or modify because it can be better, etc.

    1. I don’t just comment what the code is doing, but WHY it was decided to do it that way.

      We differ a little here, though I completely get where you’re coming from.

      I used to explain the why versus the how, but it felt like I was having to justify why I opted to do something the way I did. In some cases, this is useful but in others I found myself treating it almost like a defense, you know?

      That’s not how we should be towards one another (not that you’ve said we are, of course).

      So I might still do that, but it’s highly specific to a situation as to why I chose one route over another that I’m aware of doing.

      I know to either leave it as-is to satisfy some sort of previous reasoning/requirement, or modify because it can be better, etc.

      Bingo.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.