Web And Say All we have to say about the Web

You might be tempted to think like I did when I coded older web sites: "why would I want to spend my time documenting some pretty easy lines of code instead of developing tons of greater and funnier features ? That's pure nonsense and a huge waste of time for a simple web site!"
I couldn't be more wrong as there are a lot of benefits to documenting your code. It doesn't take that long and it might even be fun if you use the right tools.

Before we go any further, let me just remind you that Javascript and PHP (or any server side technology) are not the only languages you will want to document: don't forget about the CSS style sheets and the good old HTML web pages.
My advice to code documentation is: write as much as you can and don't worry about anything. Here are some common fears about code documentation:

• It will take too much time: did you think about the time it will take maintaining that code years after it has been written ?
• The code will become unreadable: that's why code and comment folding has been invented. The following code editors support code folding:
• Aptana
• Dreamweaver
• Notepad++
• TextMate
• and many many more...
• My web site will be too heavy and the users will see my bad comments and spelling mistakes: that's why crunchers have been invented:
• For CSS style sheets
• For Javascript: JSMin, ShrinkSafe, YUI Compressor, packer...

So let's see how hard it would be to add some documentation to a Javascript object:

/**
 * Generates a random string with the specified length
 * @param {Int} nLength The length of the random string
 * @param {Bool} bNoNumber When activated, no numbers will be used in the random string
 * @return {String} The random string generated
 */
sRandomString: function(nLength, bNoNumber)
{
  // ... code here ... //
}

Let's see a sample HTML comment:

<div id="sampleDiv">
  <!-- This is an HTML comment -->
</div>

and now a CSS comment:

.body{
  /* This is a CSS comment */
  color: #FF0000;
}

That wasn't that hard now was it ? So don't be lazy and comment as much as you can. Bytes are cheap, words are cheap, spending time trying to figure out an outdated piece of code isn't !