Comments - the simplest of all programming statements and yet at the same time the most difficult of all. Why is it we all find it so hard to write useful comments? Comments are hard.

Programming Is Hard

Contents

• A Comment To The Future Me*
• No Exceptions Ever!*
• The Magic Number Seven And The Art Of Programming
• Programming - A Life Long Challenge
• In Praise of Top-Down 

* Recently revised

Assuming that what we know today is what we will know tomorrow is an arrogance of youth - that we all suffer from.

Why explain a program that is completely obvious?

The passage of time renders all things, including programs, opaque and this is the law of nature we have to confront.

We have to come to terms with the truth of:

what I understand well today I will find impossibly hard tomorrow

It is my first law of programming and it is one of the reasons the task is so difficult.

 Future Self

More cartoon fun at xkcd a webcomic of romance,sarcasm, math, and language

This xkcd cartoon captures this truth perfectly  - we are not as bright as we think we are, and we have to learn to make allowances for it.

What is programming all about?

Programming is about expressing a dynamic process as static text. 

It doesn't matter what language you are using, or what the task is, the difficulty is that what you capture in your code is a process . It is something that happens in time, and yet your code is a static linear document that you can read in an attempt to understand how the mechanism works. 

This is worse than looking at a blueprint of an intricate mechanism of gears, cogs and levers. In our case we don't have a visual representation of how everything fits together, just a text description. 

What does it mean to understand a program?

The understanding is about holding in your head what the values are in variables and how they change as the result of the flow of control. Even in a 100% object-oriented program to understand what is going on you have to hold the object states in your head as you figure out how the dynamics of the program plays out. 

The difficulty is also made much worse by the simple fact that one part of the program may depend on what happens at a very distant point in the text. Things that are "close" in the mechanism are not guaranteed to be close in the text. In the worst case, the dependency many be to another, altogether different, text - and you you are expected and required to hold all of this machinery in your head. 

If is often said that programs are, or should be written for humans to read and machines to execute.

Of course we are usually so pushed for time and resources that writing the program for the machine is about all that we can manage. However, even when resources are availalbe we still don't manage to write code for humans, even though we think we are trying our best.

How many times have you had that conversation about comments? 

Comments are about the simplest possible programming construct. You could even take the point of view that apart from some syntax they aren't even part of the language. 

A comment exists for you to add notes explaining what your program is doing. It is the part of your program that is 100% targeted at a human reader. This is your chance to make your program easier to understand.

Simple, easy to state, but in practice it seems to be impossible. 

Novice programmers ask - what should I comment?

More experienced programmers attempt to answer the question, but apart from the usual advice:

"don't repeat the code in the comment" 

don't have much useful to say.

We all know the waste of time this is:

//A equals A plus one
A=A+1

It is so well known as to be almost a shared joke about the way not to make comments. And there is no point in trying to put distance between the comment and the instruction:

//Add one to A
A=A+1

is still a repeat of the content of the instruction.

Indeed this sort of comment leads to the opinion that we shouldn't bother with comments at all. "Write the best code you can and let it speak for itself" is an attractive proposition but even the best code in the world has a hard time saying everything it needs to say. 

Comments are an extra channel straight to the human and it is your opportunity to explain what it is all about.

Providing comments to explain your code is an obvious objective, but at the time you are writing the code it all seems so obvious that all comments you consider making seem to come down to repeating what the code says.

Commented

More cartoon fun at xkcd a webcomic of romance,sarcasm, math, and language

When you are writing a program it all seems so obvious. If you identify anything at all that doesn't seem obvious at the time you are writing the code then you'd better write some comments because it is going to be a real evil feature at some point in the very near future. If the rule is that things you understand become increasingly difficult over time anything you are stuggling to understand now gives you no hope for the future!