Captain Obvious commentaries

It was hard to write the code so we need to write good commentaries. Besides detailed commentaries are a characteristic for quality software right?

No.

To write a useful comment is a special art – but to comment on everything ends in something like this:

  /// <summary>
    /// Home Controller
    /// </summary>
    public class HomeController : Controller
    {
        /// <summary>
        /// Index Method
        /// </summary>
        /// <returns></returns>
        public ActionResult Index()
        {
            ViewBag.Message = "Welcome to ASP.NET MVC!";

            return View();
        }

        /// <summary>
        /// Guess what?
        /// </summary>
        /// <returns></returns>
        public ActionResult About()
        {
            return View();
        }
    }

The value of comments like this is almost zero – short of you tricked a special “Quality code Metric” or followed a rule. StyleCop & Co offer an easy way to create a rigid rule type.

Rules and “less is more”

A “we comment on everything” rule makes no sense at all and seduces people to create “wrong” comments. Comments have to explain the code – why is there this and this element. That it’s the “HomeController” class I’m able to found out by myself and I also know what a constructor looks like. But why do you run these tests? What’s the technical background behind this Code?

If you write to many commentaries for your code your project members won’t be very motivated to read them. Resharper is able to run smart Refactorings – but the commentaries need to be handmade and if nobody does this (because there are too many of them) they are nothing more than dead weight.

My recommendations for commentaries:

- Why did you develop your code like this? The how is already in the code

- Rules seduce to useless comments and they need additional time during the development and especially in the code support

- You need to agree on one language in your team. German/English mixture isn’t that nice

- Always keep in mind: Is the comment an additional value for the code? If not than you don’t need the comment. Don’t mind. (Commentaries are not a must have!)

If comments get to long…

In this case you might ask yourself if your code is too complicated. Countless lines of explanation may show you that your method has to many tasks.

Other opinions about this subject

Ayende Rahien and Jeff Attwood blogged about this (old subject) as well.

I’m interested in your opinion as well

What do you think? Comment on everything? Am I just too lazy for all the writing? Do you have any code comment rules?

About the author

Written by Code Inside Team

Learn more about our team.