Question

Depending on the feedback I get, I might raise this “standard” with my colleagues. This might become a custom StyleCop rule. is there one written already?

So, Stylecop already dictates this for summary, param, and return documentation tags.

Do you think it makes sense to demand the same from comments?

On related note: if a comment is already long, then should it be written as a proper sentence?

For example (perhaps I tried too hard to illustrate a bad comment):

//if exception quit

vs.

// If an exception occurred, then quit.

If figured – most of the time, if one bothers to write a comment, then it might as well be informative. Consider these two samples:

//if exception quit
if (exc != null)
{
    Application.Exit(-1);
}

and

// If an exception occurred, then quit.
if (exc != null)
{
    Application.Exit(-1);
}

Arguably, one does not need a comment at all, but since one is provided, I would think that the second one is better.

Please back up your opinion. Do you have a good reference for the art of commenting, particularly if it relates to .Net?

Thanks.

Answer 1

I often write comments that are simply meant to help me find sections of code. (I also use regions for this.) For example:

// SERVER

Because the IDE colorizes comments, it makes it handy at times to have short comments like this to assist in mentally blocking things into segments. I usually do this for only a dozen or so lines of code. If it’s longer, then a #region seems better.

I also often write notes in my comments, sometimes as a reference for myself like this:

// NOTE: -273.15 is absolute zero in °C, used for a MinValue below

It’s not a grammatically beautiful or complete sentence, but it makes sense.

Where I tend to use more complete, structured sentences is in the summary of my methods, like this:

/// <summary>
/// Populates the properties of a Sensor object based on
/// the XML components of its data file.
/// </summary>

Those I feel are more likely to be read by someone else and it helps to have verbosity and clean formatting.