Noting Scripts

People in programming do not note adequately.

From scripts I have seen, people seem to note for themselves only. The noting is done to their experience level. They seem oblivious to the fact that someone else, with much less experience than them, might someday come along and need to tweak that script they were working on. Due to insufficient noting however, it takes them about four times as long as it normally would have done to make that alteration.

I'm no exception to this. My noting is far too often done for me. I often leave long gaps in my notes because, to me, it seems painstakingly obvious what is happening. Me a year ago would probably have quite some difficulty understanding what was happening though, and would end up wasting time having to figure it out due to these inadequate notes.

How Bad is it Really?

I'm writing this blog post because I came to add a simple addition to a class earlier and I ended up spending over an hour following three interlinking scripts about trying to understand what the previous programmer had done.

This previous programmer is my brother, business partner and mentor. I have worked with him for the past year and a half, and not only that but I learnt PHP from him before he even had a solid understanding of the language. After a few months we were teaching each other and even though we practically have identical coding standards, I still had to work out what he had done due to insufficient noting.

I did a task which should have taken 15 minutes to complete, not over an hour.

What I Suggest We Start Doing...

Use Long Hand and Use Suitable Explanations

Explain, in more than one or two words, what something is trying to achieve. I don't understand your abbreviations, and neither will the next person.

A note that reads "//chs item" above a switch statement is not wanted. A note that reads, "//switch to choose item based on the product ID (pid) sent via the GET", would be much preferred and is much more informative.

Use Large Paragraphs of Notes if Needed

If someone is about dissect your code to hopefully improve it, they are going to find it very handy to have an introduction explaining what it is you were trying to achieve.

Classes and functions are the main targets of this heading. I have written, and been presented with, functions that were over 300 lines long and classes spanning more than ten times that amount.

Unless you are there with them to explain what it all means, then they're going to waste time figuring that out. A short paragraph, five to ten sentences long perhaps, explaining the purpose of these large functions and classes would be very useful and would save much time.

Note Repeated Sections

Do not abstain from writing a note somewhere because 100 lines above it or in another script is an identical block of code. The next person to read your scripts isn't going to read them in the same order that you created them meaning that when they get to a 30 line block of code with no notes they won't know what it's purpose is.

Groups

If you have a group of functions all relating to the same purpose, group those functions together in a note. E.g.

// *** Ajax handlers for anonymous users *** \\
    function a(){}
    function b(){}
    function c(){}
    function d(){}
// *** End of Ajax handlers for anonymous users *** \\

Don't forget to note those individual functions too. I find the ending note necessary as it clearly separates the grouped functions from the non-grouped functions. You might find indentation enough?

Not only does plentiful noting help others learn your code, I have found it helps you in several ways too. Returning to old, forgotten scripts, is much more pleasant if you don't have to remember/learn what it was you did again. Bug finding is quicker because you can scan notes rather than scan code. And when learning something new, you can annotate the code to your standards. Who can understand you better than you?

So I reiterate, notes please!

What noting techniques do you adhere to?