Little Secret

September 24th, 2008

I’ll let you in on a little secret. The key to writing good comments is … (rolling the drums) … not writing them at all! Let me elaborate on that.

To me, there are two kinds of comments:

  • The ones who appear right in the guts of a particular method.
  • The ones who appear right above a particular method, mostly in the form of XML comments.

Code comments

I try to avoid these kind of comments at all times. Sure, there is a time and place for comments like these.  But if I do feel the urge of writing a comment for clarifying a piece of code, then I turn back to the code, looking for a better and cleaner way of expressing my intent. If I’m just too stupid and can’t find a cleaner way for writing those particular lines of code, then and only then would I consider to put a comment in place (probably feeling bad and miserable for the rest of the day).

Writing a comment clutters the code. Besides that, a comment gets out-of-date sooner then Master Yoda can use his lightsaber. Most developers just don’t have the discipline for maintaining comments. It’s all about finding the best way to communicate with the future readers of the code. The best way is through the code itself, writing code comments as a miserable second.

XML comments

A few years ago (roughly 25 years on the IT calendar), when I stepped out of the C++ world into the .NET world, I found this tool called NDoc. Back then, this was one of the coolest tools in my tool bag. The entire world was telling me that writing comments was actually a good thing. So I did. I wrote XML comments for practically every method I’ve put out. Nothing could stop me.

Over the years however, I’ve come to my senses (it was just my time, it was just my time). Today, I use XML comments sparingly. The only time I ever use XML comments is for writing documentation for public API’s that are going to be used by other developers in other teams. Even then I feel bad about it because I almost know for certain that nobody is going to read them.

Again, I pull the card of maintainability here. The code changes, but the XML comments mostly never do. I’ve also seen too many of these:

/// <summary> /// The first name. /// </summary> public String FirstName { get { return _firstName; } } /// <summary> /// The first name. /// </summary> public String LastName { get { return _lastName; } } /// <summary> /// The first name. /// </summary> public String Company { get { return _company; } }

See what I mean. Notice the clarifying nature of the comments? Notice the implementation of copy-paste driven development? 

So kids, stay away from comments. If you care about what you do as a professional developer, then you try to communicate using lines of beautiful code.

Ciao

  • http://gregbeech.com/blogs/tech/ Greg Beech

    If you’re working on code that is simple enough to write without inline comments then I don’t envy you. The most interesting code needs literally blocks of comments to indicate what’s happening, why things are being done, etc. They are used to explain why a particular approach was taken, and perhaps more important what other approaches were considered and why they were not taken; this simply cannot be done in code. Comments are particularly important in multi-threaded code to explain potential race conditions etc.

    My assertion is that code without comments simply doesn’t work: http://gregbeech.com/blogs/tech/archive/2008/08/04/code-without-comments-is-code-that-doesn-t-work.aspx

  • http://www.marisic.net Chris Marisic

    I suggest using Ghost Doc http://www.roland-weigelt.de/ghostdoc/ This tool will auto generate comments for you for methods/properties based off the naming structure along with the parameters.

    Combine this with Resharper http://www.jetbrains.com which will inform you when comments for methods have parameters that don’t match or don’t exist or do exist and shouldn’t.

    These tools can easily lead to development with zero comment stagnation. I agree with you for in code comments they should only be used on very hacky solutions and for nothing else. Everything else that SHOULD be commented needs to be refactored into variables with proper names for what it is, to seperate methods or even entirely new classes to avoid the need for having to read anything other than the code itself.

  • http://elegantcode.com Jan Van Ryswyck

    @Chris: I’m a GhostDoc user for as long as I can remember. The tool is nice for micro-comment productivity, but if its output can be generated from the code itself, then what’s the point?

  • http://panteravb.com Chris Carter

    “…but if its output can be generated from the code itself, then what’s the point?”

    @Jan: how is the output from Ghostdoc generated from the code itself?

  • http://elegantcode.com Jan Van Ryswyck

    What I was trying to say is that if the comments can be generated by a tool, then what is the point of writing comments then. If a tool can figure it out, then a human certainly will.