Should .net comments start with a capital letter and end with a period?

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

Taking the time to write clear, readable, understandable comments is never wasted. How many times have I re-read my own comments at some later date only to struggle to understand them. People who write sloppy or badly formated comments often appy the same traits to their code.

Answer 2

If code needs a comment, then it should be well formed, because IMO there's probably a (non-trivial) concept that needs explaining.

Trivial comments such as in your examples should be avoided. They add nothing but noise.

Answer 3

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.

Answer 4

if you commenting methods in visual studio you should consider using the summary and params at the top of the method. This way you have detail about the method during code complete. Here is an example

    /// <summary>
    /// you summary here
    /// </summary>
    /// <param name="param1">Describe parameter usage</param>
    /// <param name="param2">Describe parameter usage</param>

Answer 5

I've found that when I try to be brief with comments (i.e. incomplete sentences, fragments), I often leave out key assumptions or words that would actually clarify meaning. I'm having a hard time of coming up with a concrete example at the moment, sorry.

In general, though, forcing yourself to write complete, proper sentences also forces you to think more about what you're really trying to say with the comment. I've often caught myself rethinking what I really want to include in a comment by writing it out in full.

There's no good reason to sacrifice clarity at the altar of brevity. Someone will need to understand the code in the future. The comments are for them, so make them easy to grok.