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:
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:
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 !
Recent comments
14 years 6 weeks ago
14 years 6 weeks ago
14 years 6 weeks ago
14 years 6 weeks ago
14 years 7 weeks ago
14 years 23 weeks ago
15 years 48 weeks ago
15 years 49 weeks ago
16 years 13 weeks ago
16 years 13 weeks ago