Reconstruct the Context

The reason why we regard each statement in a program as blindingly obvious when we write it is that we have the context. As you program your brain builds an internal model of the dynamics of the program. 

It is as if the program was an old fashioned gear wheel watch and when you look at a particular gear you can see what it is doing and how it relates to the other gears. However when you come back to the same program you don't have the mental model and now you have a gear wheel out of context - It's just a gear wheel. And while you may understand what a gear wheel is you will have no idea what its purpose is in relation to the other gear wheels that you are exploring. You no longer see it in relation to all the other gears. 

If you study the program for a long time. Read it, think about it, trace though what it is doing then, if you keep at it, then your brain will eventually, and usually imperfectly, reconstruct the mechanism and then some things start to seem "obvious" again.

Why is the reconstruction so hard?

The reason is that when you are writing the program you are working from the watch model in your head to the code on the page. You are reducing the dynamic process to the static text and you understand how the whole fits together - the code is just an expression of what you already know. 

When you try to understand even a small part of the code of a program you wrote some time ago the situation in very different. You are now trying to reconstuct the model you had in your head when you created the program from the code you wrote and this is much tougher.

Of course, if you are an experienced programmer you might have worked on so many programs that you have a postulated model for the code. The downside is that if you postulate the wrong model then it will take you quite sometime to notice that things aren't working out. Perhaps worse is the chance that you might make changes to the program making the wrong asumptions and so introduce subtle bugs.

So what all this means is that when you are writing the program you are in the worst possible position to write any comments that might help your future self.

Everything seems obvious and nothing is worth commenting on. When you return to your program you really wish you had made comments that might help your future self sort out what is going on. The same reasoning applies when the person reading the code is someone else and not you but when it is you it brings home the fact that you failed to communicate what you once knew and now no longer understand. 

So what can we do?

Some programmers do have a skill and facilitiy that helps them see what needs to be said to convey the mechanism that gives rise to the program. They naturally write good and helpful comments. 

You can learn this trick if you start to think about the model in your head rather than the code on the screen. At the point you are writing the code you have the model that sums it all up in your head and it is this and its relationship to the code that you need to record. 

So you may well write:

A=A+1

but the comment that is needed isn't anything to do with adding one to A.

What you need to do is make a comment that explains why you are incrementing A at this point. Is it a counter of events or resources? Is it an internal state indicator or linked to something in the external world? How is it used by the rest of the program and what valuable task is it performing in the entire mechanism. 

Comments should be mostly about the role that the instruction serves not the meaning of the instruction - which is usually obvious for all time.

There is one other big trick that you can make use of - partial forgetting.

If you leave your commenting for a few days the inevitable happens, you forget. 

You could sum up the idea as:

"Step away from the code and take your hands off the keyboard".

You might think that the forgetting is a bad thing. Surely the time you should create meaningful comments is when you are on top of the code and understand it? 

No - this is exactly the time when everything seems obvious and not in need of any comments at all. Wait a few days. Wait until the code starts to look a bit unfamiliar, like someone else's code.

Then go back to it and start to add some comments. When you realize that you don't quite follow it then you write the comments that result from your discoveries. You should have just enough of the mental model in your head to recreate it all perfectly and the effort of recreation drives the comments to make it easier the next time you have to do it.

How long do you have to leave it?

It all depends. If you are young and working on only one project then it might take a week. If you are older and work on multiple projects - ten minutes is often enough.

Comments are best made from the fog of forgetting. 

Related Articles

Teach Concepts Not Just Code

What makes a programmer

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

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info