I'm not talking about general comments found across the web - those frequently suck and I even wrote an extension to hide them all. No, I'm talking about comments in code, which (done right) are absolutely helpful and even necessary.

Comment everything!

One of the first things a lot of students learn when they start programming is "comment all the things!" I'll assume it's with the best of intentions that instructors are trying to get students into the habit of including commentary alongside their code. But since syntax is already conveyed in higher language and not ones and zeroes, that level of verbosity is often completely unnecessary.

Not to mention, you start out meaning well...

// print out "what's your name?"
Console.WriteLine("What's your name?");
// get the user's name
string name = Console.ReadLine();
// print out a greeting
Console.WriteLine($"Hello, {name}!");

... but after a few iterations things just don't match up anymore. Especially as deadlines approach.

// print out "what's your name?"
Console.WriteLine("Welcome! What's your favorite color?");
// get the user's name
string color = Console.ReadLine();
// print out a greeting
Console.WriteLine($"Your favorite color is {color}? I like turtles.");

Me: But I'm gonna go back and update them later!
Narrator: He wasn't.

Comment nothing!

And so, the pendulum swings and the absolutists among us lash back with a fiery "comment none of the things!" I'll assume it's with the best of intentions that those developers are trying to get you to hate yourself 6 months from now when you revisit your code.

If someone tells you that your code should be self-documenting, what they generally mean is that the "what" of your code should be fairly self-explanatory. The previous comments were redundant of course, but in general if you have a comment explaining what a few lines of code are doing - what, and not why - then it might mean you should pull them out into a separate method and remove the comments. Doing that will tend to DRY up your code too.

I wrote two examples of code that functionally do the same thing. Check out the difference.

  • The first one is stocked with all kinds of helpful "what" comments describing a line or two at a time. Can you tell at a quick glance what it's doing? What if I asked you to jump in and validate the customer's birth date, or change the error when the dollar amount is entered wrong?

  • The second one replaces the comments by breaking the code into a series of methods with explanatory names. Now can you glance at the "Main" method and quickly get the gist of things? If you had to change how the user is validated, it's easier to see where to look first.

Comment the Why and How from a thousand feet up

But neither the comments nor the updated method names says much about why things are done the way they are, or what the business goal is or how this particular code achieves that goal. That's what a Really Useful Comment does. So when you or a coworker comes back next month or next year, you can remember why you wrote that random number generator the way you did.

If you're looking for examples, check out source code for languages you like to use. Since language designers most definitely want everyone using their language to know why it does what it does the way that it does it, you're likely to see a lot of detailed commentary.

Scroll through some these classes and modules, and consider whether the comments simply repeat the syntax, or whether they provide valuable information about why things were written the way they were, when someone might want to use them, and how to use them the right way.

When you add your own comments (and ignore anyone who tells you to never use them), aim to comment on the thousand-foot view.. and the hundred and the hundred-thousand. No piece of code is ideal, everything can be nitpicked and debated to death. It's important to explain why you picked the code you did, what it's supposed to achieve, and how it does it... for others and for yourself!

On top of that, if you follow the recommendations for where to place your comments, you can even use tools to generate documentation from them. In .NET, there's XML comments and Sandcastle. In Erlang, there's comment tags and EDoc. In Ruby, there's apparently RDoc::Markup format and RDoc. These docs could potentially be loaded onto an intranet where other employees could browse the codebase without having to open the source code directly.

The images were from xkcd - commented, laws of physics, and random number.