A Comment Saved Me Today

Patrick Work Related

I like to think I have a very strong trust in all the members of the team I work with to tell me things I need to know to get my job done. My team members may not always be there right next to me, feeding me tidbits of information, so I trust them to leave what they were thinking in the code they leave behind. Sometimes it is harder to read some people’s thoughts, but most of the time, I get what they are saying. It’s always a great day when someone has the courage to put that comment down that saves you hours of trying to work out why something works the way it does without delving into its great recesses. Thanks for the comment and the hours you saved me today in my bug fix.

6 Replies to “A Comment Saved Me Today”

  2. Unfortunately, the cause of the problem is in a library that is out of our hands and is not completely obvious straight away.

  3. I’m probably preaching to the converted here, but I completely agree with The Other Fowler on this one, non-Javadoc comments is badness. As The Main Fowler preaches, if it needs a comment make it a method. If it needs more detail, provide it in the new method’s Javadoc. To me that’s more readable, and as an added side-effect, more prone to refactoring. Also – isolate that cruft! Build your API on the crufty API like JWebUnit has done with HttpUnit.

  4. Sure, comments can be a smell, but I remember leaving some behind on Pat’s project – and I’m very happy if they were of help. Sometimes a descriptive comment can be the pragmatic way to describe intention, especially in the case of a workaround like this:

    “The reason this hibernate query is constructed with a date literal rather than a parameter is that for some reason the JDBC driver won’t use the column index if the value is passed as a parameter. See http://www.jnetdirect.com/forum/viewtopic.php?t=9 for more details.”

  5. Daz – absolutely – perhaps I should have emphasised the *even better* part of my comment. Basically

    code that doesn’t need comments

    is better than

    code that needs comments and has them

    is better than

    code that doesnt need comments and has them

    is better than

    code that needs comments and doesnt have them

    Your example can’t easily be fitted into the first category so you drop down to the second.

    PS wow I am now *The* Other Fowler 🙂

  6. Fair point. In the rare circumstance you need to explain implementation workarounds (perhaps more controversially termed ‘hacks’), going to the effort of, say, extracting the workaround to a private method with corresponding explanatory Javadoc may be overkill. But this strategy could be useful if, for instance, you wanted to discourage the team from using in-line comments as a hard and fast rule enforced through a CheckStyle like tool. Personally I think the risk of having sorts of problems like these http://www.melalouise.net/mattblog/archives/000053.html is too great to allow it.

Comments are closed.