Tagging comments with Must/Should/May

Internet protocols are described by RFCs - request for comments - issued by the Internet Engineering Task Force. The words “must”, “should”, and “may” are used often in these documents to describe what hosts need to do in various situations. As such, the words themselves are defined in RFC 2119.

Back when I did Unix network programming I started to use these words for tagging code comments. Sort of like “hack:” or “todo:” comments, but with a built-in priority. This works great for me, as I can then search for “MUST:”, “SHOULD:”, and “MAY:” tags in the code and see the stuff prioritized. “MUST:” flags unshippable issues, “SHOULD:” is serious business and should be near zero, and “MAY:” is for possible refactorings and low priority stuff. Ideally all tags are temporary of course, as issues are resolved one way or another.

In general I believe in writing expressive code rather than comments, but these tags have come in handy. Plus they’re fun - there’s something to be said for cultivating the quirky traditions of computing.

Jon Postel

January 7, 2009 at 12:33 am | Filed Under Programming
Feed Icon Subscribe to blog

 

Comments

3 Responses to “Tagging comments with Must/Should/May”

  1. kgwagner on January 7th, 2009 1:14 am

    That’s a good system.

    I also like to write very expressive code that reads well on its own. But, I’m a firm believer in comments. They’re essentially free, in that they don’t compile so they don’t add any size or complexity to a program. Then, they pay you back later when you look at a piece of code and wonder what in the hell you were thinking about when you wrote it.

  2. Srikanth on January 7th, 2009 2:52 am

    I do it with TODO and FIXME tags :)

    In fact, I’ve written a post on how I use these to good effect with Eclipse IDE:

    http://blog.srikanths.net/2007/12/filter-your-tasks-view-in-eclipse-using.html

  3. Gustavo Duarte on January 7th, 2009 10:49 pm

    @kgwagner: that reminds me of Code Complete, the chapter on Comments where Steve McConnel has the Plato-style dialog about comments. heheh.

    You know, certainly the answer is not zero comments. So how much? I certainly agree that comments do help. I guess in general though I try to do short methods with descriptive names as a way to minimize the need for them.

    But there are many why’s that code won’t tell you and comments can. Also, some high level comments to give an overall picture of what’s going on can be hugely helpful. Those are two places where I think comments can be used really well.

    @Srikanth: Cool idea. You can still do MUST(Srikanth): though ;) A comment DSL!

Leave a Reply