I was doing some work at $DAYJOB today and came across what appeared to be a bug.
When we generated RSS or Atom feeds, we always used the content-type "application/xml" in our HTTP headers. While this isn't necessarily strictly wrong, it's not quite as right as it could be, since we could use "application/rss+xml" and "application/atom+xml" respectively.
I made just such a change and asked for feedback from the original developer of this feature. He mentioned that some browsers might handle the original content-type more gracefully. Some quick testing proved him right. IE6 will display the formatted XML (with tags) for "application/xml", but for the other two content-types it just prompts the user.
Given the goals of our app, the prompting behavior isn't as desirable, so I reverted my change, but left in a comment about why we used this particular content-type. Of course, if that comment had been there originally it would've saved me some time.
This lead me to think of a general rule, which is comment your "wrong" decisions. As programmers, we often have to sacrifice technical correctness for a variety of other factors, like user experience or performance. Commenting instances of such things in the code is really valuable to the next person who comes along. That way they know that the decision to do the "wrong" thing was intentional, and why that decision was made.
Otherwise it's all too easy to "fix" things and cause a problem.
Note that this is a case where tests wouldn't necessarily help, since it's just as easy to assume the tests are testing for "wrong" output. The key here is the rationale for the decision.
I guess this is a special case of the more general comment rule I follow, which is that your comments should explain why, not what.
Which end user is interested in an XML source dump?
