Since my very first app in C#, I’ve felt a bit like an, admittedly boring, non-conformist. It started at DeVry with the traditional Hello World project, for which I received a whopping 0 of 100. When I asked the professor how on earth a functioning program which fully matched the project requirements could be a complete failure, the professor explained that I failed for not having comments.
Apparently, the following program is so vastly complicated as to be incomprehensible without the accompanying green text.
| public static void Main(string[] args) | |
| { | |
| // Writes "Hello World" to the console. | |
| Console.WriteLine("Hello World"); | |
| } |
Now the professor, you, and I all know that the comment doesn’t really help in this case. What’s important is, it reinforces the good habit of commenting your code. Really though, how good a habit is it?
One of my favorite stories from the excellent show QI, is the line about Samuel Johnson’s definition for, “sock.” You guessed it, “Something put between the foot and the shoe.” Astonishing in it’s clarity, right? Imagine you have no idea what a sock is. How many possible items could it be? What material is used to make it? Most importantly, why are you putting it between the foot and the shoe?!
Without knowing what purpose the object serves, how are we to use it correctly? Yet, I consistently see definitions such as this in comments, or worse yet, the dreaded:
| /// <summary> | |
| /// Sock | |
| /// </summary> | |
| public Sock Sock { get; set; } |
Surely you jest! You mean to say that a property of type Sock, which you have named “Sock”, is a… Sock?! No!
So what’s my point? Not everyone’s a wordsmith. Too true. I struggle with comments all the time. My point is that we need to stop teaching new developers to mindlessly shove green text in their code. Where code and comments fail to add value, they reduce value. Every line read which does not enhance understanding, is a delay and a distraction on the path to grokking the solution.
If you can’t find a better descriptor for your field/property/method than the name itself, don’t bother putting in a comment. It just takes up space on your and my screen.
That said, try to leave useful comments which add value. If you’re using a little-known class, or a hot new open-source library, add a link to a good tutorial or the github page. Give the next guy a resource. If you can’t think of a way to add clarity to a property declaration, work on something else. Grab a coffee. Come back to it when the code is stale enough in your own mind that you can see what I’ll see. That would be the giant, “What in the Sam Hill is a Metaphor<string>?
Most of all, if the comment won’t add value, don’t write it. Comments aren’t there to please the professor, or Ms. Manners, or the standards committee. They’re there to help the next developer use your awesome tool. Oh, and remember, Dr. Johnson was a brilliant scholar. Even his definitions weren’t always perfect.
On a final note, I leave you my definition of a sock:
| /// <summary> | |
| /// A cloth sleeve which protects and insulates a foot. | |
| /// </summary> | |
| /// <remarks> | |
| /// A sock is generally a cloth tube with only one open | |
| /// end. It is worn over the foot and can help to keep | |
| /// the foot warm in cold weather, as well as prevent | |
| /// chafing when worn between the foot and a shoe, boot | |
| /// or similar garment. | |
| /// </remarks> | |
| /// <example> | |
| /// This shows the basic use of a sock. Please remember, | |
| /// the sock is worn over the foot and under the shoe. | |
| /// <code> | |
| /// class Foot | |
| /// { | |
| /// public Sneakers Shoes { get; set; } | |
| /// public Socks Socks { get; set; } | |
| /// | |
| /// public void DonShoes() | |
| /// { | |
| /// this.DonSocks(this.Socks); | |
| /// this.ShoesWorn = true; | |
| /// } | |
| /// | |
| /// public void DoffShoes() | |
| /// { | |
| /// this.DoffSocks(this.Socks); | |
| /// this.ShoesWorn = false; | |
| /// } | |
| /// } | |
| /// </code> | |
| /// </example> | |
| public class Sock | |
| { | |
| } |
Fun times with Functions 