Jason Baker wrote Myths About Code Comments. I like posts like this – they get me thinking about the assumptions I make in my day to day work.
In short, Jason says the following are myths:
- Comments are free
- Comments make code more readable
- You should comment every function, method, class, and module
- Code must always be "self documenting"
In particular, I think the first and second points are intimately related. Anything that goes into a product – documentation, code, comments, tests, etc. – is never free. Anything that goes into a product incurs not only the cost of initially creating but also the ongoing cost to keep up to date. If you avoid the ongoing cost by not keeping all items up to date, the result is that the code and the supplementary material diverge – which leads to the myth that comments make code more readable.
I have written about accidental correctness before. I recently released a fix for an item that was "accidentally correct" for nearly a year.
Early last year, we released a new feature which used Lucene to index the entries. As part of the UI, the entries were displayed – newest entries first. Things worked great. Until the new year.
It turns out we were sorting not on the date but on the date string stored in Lucene. The string was in MM/DD/YYYY format. So, the entries that started with 12 were before 11, etc. All appeared correct. The newest entries were at the top. Then January came. All of a sudden, the newest entries were at the bottom of the list. Sigh.
Lesson re-learned: make sure your test dates span years.
Some time ago, I was looking up an HTTP response code and came across a handy flow chart of HTTP response codes on Alan Dean’s (http://thoughtpad.net/alan-dean.html) site. Unfortunately, the link I had written down was down. I was able to find the graphic on Flickr. A useful reference diagram.
8:12 AM Feb 28th, 2010
Hold vendors liable for buggy software – http://bit.ly/c2y5YJ
11:01 AM Feb 27th, 2010
2010 CWE/SANS Top 25 Most Dangerous Programming Errors – http://bit.ly/cNVjit
9:37 PM Feb 23rd, 2010
Use Speedy Tab Shortcuts to Increase Your Firefox Productivity – http://bit.ly/crxdMx
8:06 PM Feb 19th, 2010
Vanish – Self Destructing Digital Data – http://vanish.cs.washington.edu/
7:35 AM Feb 15th, 2010
Making the IE voodoo doll – http://bit.ly/8nZW
8:53 PM Feb 12th, 2010
2010 Pacific NW Software Quality Conference Call for Papers – http://www.pnsqc.org/2010-conference/call-for-abstracts
6:59 AM Feb 8th, 2010
When should I use a semicolon? – http://cache.gawker.com/assets/images/17/2010/01/500x_semicolon.jpg
10:17 AM Feb 7th, 2010
Top 10 Themes from 2010 Davos – http://www.businessweek.com/managing/content/feb2010/ca2010022_162429.htm
8:56 PM Feb 5th, 2010
I wish I could drop support for IE6 – http://lifehacker.com/5460043/google-apps-drops-support-for-ie6
6:17 PM Feb 2nd, 2010
RT @Conenza: If youre having trouble getting your bosses to adopt social networking, the Pope may be your ally. http://tinyurl.com/ydj4g2q
7:20 PM Feb 1st, 2010
James Whittaker’s “Interviewing Insights and Test Frameworks” – http://www.testingreflections.com/node/view/8437