Code comments are DEAD…or ARE they??

Greg L. Turnquist
5 min readFeb 2, 2023

We’ve all dabbled with code comments. In fact, when learning programming, it’s one of the first little things you learn.

/**
* We were all shown how to add our own comments to code,
* perhaps on Day 1.
*/
public class MyExample {
public static void main(String[] args) {
System.out.println("Really cool, ehh?");
}
}

Stuff like this is something coding instructors love to show. And it’s cool, right? Write all the commentary you want about your code.

  • How it works
  • Why you picked this algorithm
  • Detailed explanation about HOW that algorithm works, to help you out the NEXT time you have to read that chunk

That last one is key. Why?

Because our ability to read code ebbs and flows. Sometimes, when we revisit a chunk we haven’t seen for six months, getting back up to speed can be tough. A comment explaining the algorithm in HUMAN can be vital.

And this is where comments can sabotage us.

Because what happens when we ALTER the code? What happens when we write a detailed explanation about how it works, but then we change it five times. And when the other person on our team makes a few tweaks of their own?

And that wonderful, beautiful comment was NEVER updated.

When it’s time to get up-to-speed, the comment may be worthless. It may flat out wrong. Or…it may actually be more insidious than that. What if the code had corner cases later fixed, but the comment doesn’t cover that?

This is the reason the sofware development community has generally declared comments to have little redeeming value. Talk to any pro coder with more than a few years under their belt, and they’ll tell you not to sink your hopes into code comments.

And such a sweeping generalization, would turn to be wrong.

Comments have a vital, critical value in our code. But they must be used judiciously.

Licensing and credit

Every file in your codebase should have its shorthand license in a comment at the top of the file. When people run into your code, the terms of interacting with it should be plain and…

--

--

Greg L. Turnquist

Sr. Staff Technical Content Engineer at CockroachDB • YouTube Content Creator at https://youtube.com/@ProCoderIO • Best-Selling Author • Coffee Lover