2010.07.06

Always comment weird things!

This is more a reminder to myself than anything else. It’s about something simple that I’ve been trying to do since a long time and that I hope most people been doing it too…

Always, I’ve said ALWAYS, comment things that may be strange to other developers (or even to yourself in the future) and/or fixes specific bugs, it can save you a lot of time…

Why

  • Because the code may need to be updated later.
  • You may forget why/how you have done something (or maybe why you have not).
  • Someone may get confused and fix something that wasn’t broken. (imagine re-opening a project after 1-2 years)
  • It can save you a lot of time.
  • It can be used as a reference on future projects.
  • People may learn from your source code (including yourself).

Why I decided to talk about it?

A couple weeks ago I was trying to do a stripped down version of swffit and I decided to code it from scratch since I didn’t needed most of the things, I also needed to add some things that would break the basic functionality and since I’ve coded the original I thought it wouldn’t take too long… – long story short I’ve spent around 30 minutes trying to fix a bug that I’ve already fixed 2 years ago but I couldn’t remind what I did to fix it… the solution? I’ve just looked into swffit source code and in one of the lines I had one comment that described exactly what I’ve done to fix it… I would probably lose way more time if it wasn’t by that specific comment.

Don’t over do it!

Try to keep the amount of comments on your source code reasonable, only comment things that are important otherwise it will make your code harder to read, it’s like typing a full text using bold font, it simply loses the point of doing it.. you need contrast to make things stand out

Dumb comments

A dumb comment is a comment that doesn’t help you (or other programmers) to understand the code. Couple examples of what you should not do:


x = 0; //sets x to zero

if(y == 10){ // if y equals 10
    ...
} else { //if y is different than 10
    ...
}

Smart comments

Smart comments are those used to describe hacks, optimizations, bug fixes, things that may not be easy to read/understand (e.g. RegExp, bitwise operations, crazy math, etc..), whatever looks weird… Examples of what you should do:


myElem.style.overflow = 'hidden'; //forces IE8 to redraw element after resize (fix bug #4)

while(n--){
    ...
    myArray[myArray.length] = n; //faster than push
    ...
}

regex = /\?[a-zA-Z0-9\=\&\%\$\-\_\.\+\!\*\'\(\)\,]+/; //valid query string chars according to: http://www.ietf.org/rfc/rfc1738.txt

kappa = 4 * ((Math.SQRT2 - 1) / 3); //find control points position (magic number) - http://www.whizkidtech.redprince.net/bezier/circle/

Reminder

It’s better to not have comments and/or documentation than to have a bad/wrong/outdated one.

Few things are worse than a documentation that you cannot trust, it’s like using a compass that randomly points you to wrong direction.

Make your life and others easier!

That’s it!


Comments

Leave a Comment

Please post only comments that will add value to the content of this page. Please read the about page to understand the objective of this blog and the way I think about it. Thanks.

Comments are parsed as Markdown and you can use basic HTML tags (a, blockquote, cite, code, del, em, strong) but some code may be striped if not escaped (specially PHP and HTML tags that aren't on the list). Line and paragraph breaks automatic. Code blocks should be indented with 4 spaces.