To comment or not to comment.
Reflections January 17, 2009
Today there was another extensive discussion about commenting your code. There are 2 distinctive different views: comment everything and comment nothing.
Yes…, nothing.
Sounds odd, doesn’t it, after constantly hearing to comment all extensively.
The viewpoint of the defender here being that nobody keeps their comments updated when they make a slight change and after a year or five these comments are not even helpful any longer but only a hindrance and a slow down. Another point was: give me any code uncommented and I will read it to you and will know what it does. Big words. But after some more probing it does boil down to not a clue anymore how and why I did it then and now indoctrinate myself in a new unit of time. Which is not a bad thing to do, re-familiarizing.
The other extreme is to comment absolutely everything. Which to a non-novice can become a too cumbersome to read as too many comments might also cloud the clear view and instant understanding of the written code.
I am definitely in the camp of the ones who comment their code and sometimes even leaning towards over-commenting. But things I use over and over and over again…, of course I’ll stop commenting them at some point. Page structure is still something I like to comment but less with the purpose of explaining but much rather do I use these comments for the specific reason of organization and to be able to glance quickly across several hundred lines of code and see a comment shining like a beam and a block delineator. It helps speeding thing up. In combination with applications that allow for code folding - such as Aptana - a huge page can shrink to a clear and concise half of page and the comments are the headers for a collapsed group.
My overall, basic approach to commenting and which has worked well in the past is to over-comment a lot during development and when the project is functioning and coming to an end remove all redundant comments. This especially applies when I dive into projects containing PHP, Javascript, Ajax, Flash and the lot which I do not do on a daily basis.
The motto here is “it is always faster to remove some lines of comments than trying to remember why we had written something the way we have”.