Minimal
stressed for motivation and achievement2006-03-25
BUG #171: Blank title didn’t work here
The other day at work, I came across a diktat stating that any bug fixes should be given a code comment pointing the reader to the relevant issue in our defect tracking system. Well, until someone explains the rationale to me, I’m going to ignore that.
To look at how dumb this is (IMHO), here are a couple of analogies to consider:
- When you write a document in Word, do you insert comments throughout it, saying things like “Used to say ‘in order to’, but that’s too wordy (MR)”? Sure, they might not print out, but they’re still getting in the way for the person editing the document.
- When you’re doing the CSS for a web page, do you litter it with comments like “Tried using javascript for this, but it wasn’t reliable (MR)”? No! It would just be getting in the way.
So, why the hell should I litter my C# code with comments that refer to a bug that’s no longer exists? What do I care if there was once a bug there? What’s important is that the code now works—we can record the bug fix in our check-in comments. What valid reason might I be overlooking for this behaviour?
Update: the diktat is no longer a diktat; more a recommendation. And it now sits alongside another recommendation that says “where reasonable, write a unit test to prove the existence—and resolution—of the bug”. Result. :)
I don't agree with the diktat, I'm just trying to think of a rationale for it. There are odd times where I have noted a bug number next a change to help somebody understand why I changed it. But those times are few and far between and almost always when I've been working in "someone else's" code where the ideal solution would have been a more significant refactoring of the whole lot.
1. The need for a comment within a function can often signify that the function could be re-written in such a way as to illustrate its algorithm better. Refactoring can make a lot of this stuff clearer.
2. I once found a comment in the code which described very clearly why something was in there, and which bug it had fixed. I realised that the comment was actually taking the place of a test case. I turned it into a test case, which duly failed, and then I discovered that other changes, had re-introduced the bug. The lesson? Comments don't avoid bugs, long-term. Test cases are better.
Ignore the dictat, write self-documenting clean code and test-cases. I've been doing this since January and it's absolutely smashing!
Not at my desk, they didn't. ;-)
Very few people update code comments when they update code, as a result the comments become out of date and ignored.
: 12:15 pm : 12:00 pm<< Home
Archives
April 2002 May 2002 June 2002 July 2002 August 2002 September 2002 October 2002 November 2002 December 2002 January 2003 February 2003 March 2003 April 2003 May 2003 June 2003 July 2003 August 2003 September 2003 October 2003 November 2003 December 2003 January 2004 February 2004 March 2004 May 2004 June 2004 July 2004 August 2004 September 2004 October 2004 November 2004 December 2004 January 2005 February 2005 March 2005 April 2005 May 2005 June 2005 July 2005 August 2005 September 2005 October 2005 November 2005 December 2005 January 2006 February 2006 March 2006 April 2006 May 2006 June 2006 July 2006 August 2006 September 2006 October 2006 November 2006 December 2006 January 2007 February 2007
