Taking the time to make notes

How important is it?

[dvduval]

I'm pretty new to writing code. I've been writing html for about 5 years, but ASP, PHP and CFScript are a little newer to me.

In html I never really made notes about the code I was writing. I guess that is because it's east to see the results. I see more notes when I see coding in scripting language.

How important is it?

[ScottM]

I'm just starting to learn PHP and I find myself going back and writing notes all the time.

In fact, even in html, I'll put a few notes in if I am doing something new that I might not do again for several weeks.

It's a lifesafer!

[senior mcinvale]

its a good idea to put comments in your code if you plan on modifing it in the future.

when scripts get large its easy to forget why you did something.

[jamesa]

It's amazing how your own code can look Greek to you after you haven't looked at it in a while. That was especially true when I was starting out (now I tend to reuse a lot of code so it stays familiar).

How important is it?

It's very helpful.

You don't need to go overboard so that you're commenting every line. In most cases it's fine to just to label blocks of code with short statements like "building SELECT query", "formatting email message", "initializing variables", that kind of thing...

it's also nice to explain what the script does at the very top so later if you're looking for the script that formats the search results page, for example, it'll be easy to find.

Whenever you do something that's a workaround, a kludge or otherwise non-standard thing then DO explain it in detail so that whomever reads it in the future understands why and what you were trying to do.

[willybfriendly]

I often comment my code before I write it. I then have an outline of what I need to accomplish right there in front of me. Good comments are essential. Saved my tail often when I was chasing bugs.

WBF