Your code should be clear enough and easy enough to read that you don't need comments.

You should be naming your methods and variables so clearly that it is obvious what is happening in your code.

The exception to this would be when the code is doing something out of the ordinary and you need to add an explanation. If you keep your methods small enough you can put the comments in the summary above the method.

The problem with comments is that when the code gets updated if you don't update the comments, they will be wrong.

The same can be said about summaries above the method or class. They can very quickly go out of date.

Watch my video about this topic

Consider these two examples

This one is busy with unnecessary comments and magic numbers:

static string GetPrettyDate(DateTime d)
{
    // 1.
    // Get time span elapsed since the date.
    TimeSpan s = DateTime.Now.Subtract(d);

    // 2.
    // Get total number of days elapsed.
    int dayDiff = (int)s.TotalDays;
    // 3.
    // Get total number of seconds elapsed.
    int secDiff = (int)s.TotalSeconds;
    // 4.
    // Don't allow out of range values.
    if (dayDiff < 0 || dayDiff >= 31)
    {
        return null;
    }

    // 5.
    // Handle same-day times.
    if (dayDiff == 0)
    {
        // A.
        // Less than one minute ago.
        if (secDiff < 60)
        {
        return "just now";
        }
        // B.
        // Less than 2 minutes ago.
        if (secDiff < 120)
        {
         return "1 minute ago";
        }

        // C.
        // Less than one hour ago.
        if (secDiff < 3600)
        {
        return string.Format("{0} minutes ago", Math.Floor((double)secDiff / 60));
        }
        // D.
        // Less than 2 hours ago.
        if (secDiff < 7200)
        {
        return "1 hour ago";
        }
        // E.
        // Less than one day ago.
        if (secDiff < 86400)
        {
         return string.Format("{0} hours ago", Math.Floor((double)secDiff / 3600));
        }
    }

    // 6.
    // Handle previous days.
    if (dayDiff == 1)
    {
        return "yesterday";
    }
    if (dayDiff < 7)
    {
        return string.Format("{0} days ago",
        dayDiff);
    }
    if (dayDiff < 31)
    {
        return string.Format("{0} weeks ago",
        Math.Ceiling((double)dayDiff / 7));
    }
    return null;
}

This one just has a summary at the top, and uses clearly defined variables and constants instead of magic numbers.

/// <summary>
/// Returns a string representing the relative time for when the tweet was tweeted.
/// I started out using this as a base, but rewrote some of it: http://www.dotnetperls.com/pretty-date
/// </summary>
/// <param name="startDate">The start date</param>
/// <param name="endDate">The end date</param>
/// <returns>A string representing the relative time between the two dates</returns>
public static string GetRelativeTimeBetweenDates(DateTime startDate, DateTime endDate)
{
const int MAXIMUM_DAYS_IN_MONTH = 31;
const int ONE_MINUTE = 60;
const int TWO_MINUTES = 120;
const int ONE_HOUR = 3600;
const int TWO_HOURS = 7200;
const int ONE_DAY = 86400;
const int ONE_WEEK = 7;
const string DATE_FORMAT = "dd mmm yyyy";


TimeSpan interval = endDate.Subtract(startDate);
int differenceInDays = (int)interval.TotalDays;
int differenceInSeconds = (int)interval.TotalSeconds;

string relativeTime = "";

if (differenceInDays >= 0 && differenceInDays < MAXIMUM_DAYS_IN_MONTH)
{
if (differenceInDays == 0)
{
if (differenceInSeconds < ONE_MINUTE)
{
relativeTime = "just now";
}
else if (differenceInSeconds < TWO_MINUTES)
{
relativeTime = "1 minute ago";
}
else if (differenceInSeconds < ONE_HOUR)
{
relativeTime = string.Format("{0} minutes ago", Math.Floor((double)differenceInSeconds / ONE_MINUTE));
}
else if (differenceInSeconds < TWO_HOURS)
{
relativeTime = "1 hour ago";
}
else if (differenceInSeconds < ONE_DAY)
{
relativeTime = string.Format("{0} hours ago", Math.Floor((double)differenceInSeconds / ONE_HOUR));
}
}
else if (differenceInDays == 1)
{
DateTime yesterday = endDate.AddDays(-1);
if (startDate.Date == yesterday.Date)
{
relativeTime = "yesterday";
}
else
{
relativeTime = "2 days ago";
}
}
else if (differenceInDays < ONE_WEEK)
{
relativeTime = string.Format("{0} days ago", differenceInDays);
}
else if (differenceInDays < MAXIMUM_DAYS_IN_MONTH)
{
double numberOfWeeks = Math.Ceiling((double)differenceInDays / ONE_WEEK);
relativeTime = string.Format("{0} week{1} ago", numberOfWeeks, numberOfWeeks > 1 ? "s" : "");
}
else
{
DateTime oneMonthAgo = endDate.AddMonths(-1);
if (startDate.Year == oneMonthAgo.Year && startDate.Month == oneMonthAgo.Month)
{
relativeTime = "last month";
}
else
{
relativeTime = startDate.ToString(DATE_FORMAT);
}
}
}
return relativeTime;
}

I believe the second example is a lot clearer and easier to understand.

What are your thoughts on the topic? Can you offer a good case for using comments?

Want to thank me?

If I've helped you out and you want to thank me, why not buy me a coffee?

About the author

Paul Seal

Umbraco MVP and .NET Web Developer from Derby (UK) who specialises in building Content Management System (CMS) websites using MVC with Umbraco as a framework. Paul is passionate about web development and programming as a whole. Apart from when he's with his wife and son, if he's not writing code, he's thinking about it or listening to a podcast about it.

Related Posts

How to fix corrupt accented characters in Excel for a C# export as CSV

This post will help you fix the issue where you csv export has corrupt characters when opening it in…

Read Post

How to create a dynamic image from multiple images using ImageProcessor

This post shows you how I created a handler to create dynamic header images for my umbraco website u…

Read Post

How to send Slack messages programmatically using C#

In this post I show you how you can send Slack messages programmatically using C#

Read Post

How to include scripts from partial views in MVC and Umbraco

This post will show you how you can include scripts from inside an MVC partial view rather than havi…

Read Post