Blog

Little Secret

September 24, 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

If you and your team want to learn more about how to write maintainable unit tests and get the most out of TDD practices, make sure to have look at our trainings and workshops or check out the books section. Feel free to reach out at infonull@nullprincipal-itnull.be.

Profile picture of Jan Van Ryswyck

Jan Van Ryswyck

Thank you for visiting my blog. I’m a professional software developer since Y2K. A blogger since Y2K+5. Provider of training and coaching in XP practices. Curator of the Awesome Talks list. Past organizer of the European Virtual ALT.NET meetings. Thinking and learning about all kinds of technologies since forever.

Comments

Latest articles

Tags

Disclaimer

The opinions expressed on this blog are my own personal opinions. These do NOT represent anyone else’s view on the world in any way whatsoever.

About

Thank you for visiting my website. I’m a professional software developer since Y2K. A blogger since Y2K+5. Author of Writing Maintainable Unit Tests. Provider of training and coaching in XP practices. Curator of the Awesome Talks list. Thinking and learning about all kinds of technologies since forever.

Latest articles

Contact information

(+32) 496 38 00 82

infonull@nullprincipal-itnull.be

principal-it.eu
principal-it.be
janvanryswyck.com