Things are pretty hectic here in the LiveCode office at the moment. Not only are there 3 (yes three) separate versions of LiveCode out there for testing (6.6, 6.7 and 7.0), each with there own set of new features, there are also several projects being worked on that are still in their infancy. These new projects will form the basis of future LiveCode releases. It’s tricky to decide when to end development on one project and begin working on another. That’s often why as developers we find ourselves working on several things at any one time.

As we’re preparing to draw a line under the 6.5/6.6 cycle (with the release of LiveCode 6.6.2 – naturally we’ll still be fixing any bugs that crop up in these versions), I find myself doing a lot of debugging and sifting through old sections of code. And this got me thinking about coding style and specifically how we comment code. Each developer appears to have their own particular way of doing things. I’m trying to decide which I prefer. Here are a few that I have come across. What type are you?

The read the source commenter

Or in other words, the coder who views comments as optional. This coder takes the opinion that all the information you need is contained within the source itself. In reality they’re just lazy. I think I’m allowed to write this: I’m very much of this type.

For the most part, I actually don’t mind this style. I often prefer to work through the code line by line, figuring out what it does and how it all fits together as I go. As long the code is well written and I have a grasp on roughly how the given component works, it usually works out okay.

But there are some pitfalls. How many times have you found yourself in this position? You come across a line of code that you have no idea what it does or even why it’s there. What you do know is that if you remove it, it fixes a bug that you’ve spent hours tracing down. What you don’t know is the impact of removing the line. Will it pass without incident or will computers around the world suddenly start catching fire? See, a little explanation here wouldn’t go amiss.

So some commenting is useful. But how much?

The essay writer

This type of coder makes the assumption that everyone reading their code is an idiot. Often, the lines of comments far outnumber the lines of code. I once heard someone say that you should write your code with the intention that your gran should be able to understand it.

And here’s my problem with this style. I’m not an idiot (or at least I like to think not). And I’m certainly not your gran.

Working on a project like LiveCode, which has a very mature code base, you find that a lot of your time is spent poring over code, trying to figure out what it does and how it works in order to fix bugs. You want to do this as quickly and efficiently as possible. However, there’s nothing worse than when going to fix a bug, finding yourself faced with a swathe of green. It makes you feel like that to even begin contemplating fixing the issue you need to spend the next few hours sitting down in a darkened room getting into the author’s mindset. Only then will you have reached a point where you will be able to understand and comprehend the complexity of the  code that follows.

In reality, when fixing a bug, you want to do it as efficiently as possible. You don’t need to have a complete grasp on the full inner workings of the system. You just need to know enough to understand what the issue is and know that your fix won’t cause any further issues.

My opinion is that more significant chunks of technical documentation should be kept separate from the source code itself. If you find yourself having to write a lot of comments to explain your code, maybe the problem is with the code itself. Try and write clean and clear code. Often code that is well designed and thought out requires fewer comments and is much easier for third parties to understand.

The redundant commenter

Ahh, the redundant commenter. The only thing that annoys me more than the essay writer is the redundant commenter. I’m sure that this coder has good intentions at heart. It’s just they appear not to be able to put these good intentions to use. Take for example, the following lines of code:

    -- Repeat through each person in the address list
    repeat for each line tPerson in tAddressList
        . . .
    end repeat

As I’m sure you can see, the comment above is less than useless. Consider this: You’ve spent what feels like hours tracing down a bug, get increasingly more and more frustrated. At this point you would take any minor hint or guidance. Just a little something that might point you in the right direction. You spot a line of green. You think this is it, this is the comment that is going to make everything clear. You read it. You collapse in a heap of disappointment. At this point, I usually get up from my desk, go home and swear I’m never going to look at a computer again.

That may be an exaggeration, but padding out your code with redundant comments isn’t really helpful. It’s commenting for the sake of commenting. If a line of code is self explanatory, there’s no need to comment.

Finding a balance

So, comments are needed. But too much can be counter productive. So what’s a good balance? I generally try to stick to the following rules. Use descriptive names for your variables and handlers. Don’t be scared of verbosity, but don’t go overboard.

• Use a prefix system for variables (e.g. local variables, parameters, globals, script variables etc).
• For each handler, write a sentence or two describing what the handler does (not how), including a run-down of parameters it takes, what it returns and any errors it throws. If you can’t do this in a few sentences, that suggests that you may need to rethink your abstraction.
• Comment on any blocks of code that are doing something subtle or that is not immediately obvious.
• Attempt to make the code you write as clear and simple as possible. After you’ve got a block of code working, if you think you can rewrite it in a cleaner way, then do so.
• If you are working on a larger project that requires further description, do this in a separate document.

These, though, are just my thoughts and opinions that have been formed over years of looking at other people’s code. I imagine that if you ever had to work through some of my code, you’d no doubt be of the opinion that I’m full of nonsense and doing it all wrong.