By Tom

Overcommenting

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.

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:

  • Let the code be the documentation,
  • Comment only what’s necessary, such as classes and functions and blocks that may be difficult to understand,
  • 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.

    Maybe I’m Over Commenting Code (Are You?) was written by Tom. For more information about WordPress, development, and resources then visit Tom McFarlin’s blog.

    Read more here:: Maybe I’m Over Commenting Code (Are You?)