What are your thoughts on Periods/Full Stops in code comments? [closed]

Question

I saw this asked in the SO Tavern, so I'm posting the question here. I thought it an interesting question. (Of course it doesn't belong on SO, but I think it's OK here.)

Do you add periods (or, as the OP wrote, "full stops") in your code comments?

To keep it relevant, why?

Answer 1

Full stop is for ending sentences, but if a comment consists of just one sentence surrounded by code, then full stop is not necessary in my opinion. Sometimes I even don't capitalize the first letter. A detailed multiline comment, on the other hand, does need full punctuation.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Answer 2

Yes, Because comments are in English, and proper English uses punctuation.

Answer 3

Do you add periods (or, as the OP wrote, "full stops") in your code comments?

To keep it relevant, why?

For the same reason I add them when writing "normal" text - they are a part of the language in writing, and there shouldn't be anything special about them. I use them equally when writing one sentence (one line) comments as well as whole paragraphs.

Source code is not normal text, and therefore we use different rules for it. Simple ;-)

Answer 4

If you write comments one would hope they are written in English. That being case case, one should punctuate properly. Doing otherwise would be lazy.

Answer 5

If I write a full sentence (or more), then yes. If I don't, then sometimes no, but usually still yes.

I also sometimes go crazy and use exclamation points, question marks, etc. ;)

As for why, it's partly because I'm just particular like that and partly because I find that appropriate punctuation can add a lot of clarity.

Answer 6

The other answers and their popularity have made it clear that full stops are well appreciated in longer comments, and probably can be avoided in one-liners.

Another point that might be relevant is to avoid exclamation marks, especially multiples. Example:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

and

    // This code really sucks!

On the other hand, question marks are quite useful sometimes:

    // TODO: What does Crojpler.bway() actually do?

Answer 7

It depends. If I write up a big, proper paragraph explaining what a block of code does, then I punctuate it properly, like any other piece of proper writing. OTOH, when I just comment a single line of code, then I don't.

Why? - Similar to why I write emails using proper writing, while I might use shorthand sentences in SMS messages. In one case I'm sitting down to write a proper block of text, so I just automatically "do it properly", while in the other it's just a brief note to get a point across.

Real examples from my code:

Quick note comment:

// check for vk_enter

"Proper" method documentation:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Answer 8

Yes i think by this way you create a good coding convention and it also creates a neat readable code for a 3rd person reviewing your code.

Answer 9

I will always properly capitalize and punctuate when creating XML comments that I expect to be seen in IntelliSense and in our generated documentation. These are much more formal constructs and should be treated as such.

Comments just seen in the body of a code block, however, should simply be as clear as possible. It's up to the programmer how they achieve that.