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?

  • 2
    SOmetimes i do and sometimes i don't. It depends on the comments and what makes it easy to read. – Tim Nov 9 '10 at 4:07

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; 
  • 4
    +1. This looks so much like my commenting style it gave me a false deja vu. :) – Bobby Tables Nov 9 '10 at 2:12
  • 26
    No, full stop is for marking the end of sentences. It is irrelevant whether you have one or several. – Rook Nov 9 '10 at 2:59
  • 2
    <joke>Wouldn't it be better to check for exceeding int boundaries?</joke> – Dan Rosenstark Nov 9 '10 at 8:20
  • 2
    @Yar: an average is always between a and b, which by definition are always within the boundaries, right? ;) – mojuba Nov 9 '10 at 8:24
  • 8
    All my strings are null terminated, so a proper comment should always end with '\0' You don't want the next guy looking at your code to read past the end of his mind do you? – CodexArcanum Nov 9 '10 at 16:49

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

  • 2
    How about text messages? – Moshe Nov 9 '10 at 2:38
  • 4
    @Moshe, text messages are hardly proper English. – Dominique McDonnell Nov 9 '10 at 2:54
  • 8
    Hardly proper English, but I still use punctuation in them. Punctuation is there to guide the reader as to exactly what the author intended - this applies to any language, IMHO. – cjmUK Nov 9 '10 at 10:38
  • @cjmUK, Lol, yes and so do I. I thought Moshe meant it as a reason that we would not use punctuation, as I regularly receive messages like "that wd b gr8 cu there bye" which drive me up the wall – Dominique McDonnell Nov 9 '10 at 21:31
  • I nu wot u ment im wiv u all da way – cjmUK Nov 10 '10 at 11:52

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 ;-)

  • A friend of mine never captializes words in emails... because it's on the internet. To me it's fine when you adapt your writing to technical limitations like SMS, but how are emails or source code different from text in letters and books? – LennyProgrammers Nov 9 '10 at 8:40
  • 1
    @Lenny222 - Not sure what you're asking here. Emails should be written like normal text; like you're writing a letter as you say. How they are actually written (and SMSs, oh boy, don't get me started on SMSs :) Source code does not subdue to the same rules as normal text, because it has its own syntax rules. – Rook Nov 9 '10 at 13:29
  • 2
    To me source code comments are meant to be read by human beings. Why should it make a difference whether the some information is in a separate specification document or embedded in a source code comment? – LennyProgrammers Nov 9 '10 at 13:41
  • @Lenny222 - Something just occured to me, so just so that there is no misunderstanding between us. We are now talking about the source code, or the comments embeeded in it? If it is the second case, then I apologize, for I misunderstood you. In that case, the same rules go as for normal text (for comments). In the actual source code (the one that gets read by the compiler/interpreter), I don't see how the same rules could follow. – Rook Nov 9 '10 at 13:51
  • 1
    Yes, i think we agree with each other without knowing. ;) – LennyProgrammers Nov 9 '10 at 14:41

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.

  • 1
    Periods are for the end of a sentence. Comments are not necessarily full sentences. – John B. Lambe Apr 14 '17 at 14:39
  • Comments, in general, should be sentences. If not, I should ask why not. If your comments are so short that they are not sentences, are they perhaps obvious and therefore superfluous? – quickly_now Apr 17 '17 at 23:48

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.

  • If you're using question marks, do you understand your own code? – Moshe Nov 9 '10 at 3:14
  • @Moshe: Those are usually in TODOs when I may not yet fully understand my own code. – Adam Lear Nov 9 '10 at 3:38
  • 2
    @Moshe - Why can't comments include questions? Questions can be rhetorical. In fact, I often us ? in my comments - when describing conditional code, rather that a dry explanation of the logic, it is often clearer to describe the logic as a question. E.g. "Has the qualifying criteria been met? If No, display warning to user." – cjmUK Nov 9 '10 at 10:43
  • 1
    In working with large projects and many collaborators i often find those questioning comments the most important. – LennyProgrammers Nov 9 '10 at 14:44

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!!!


    // This code really sucks!

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

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

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.
  • .NET developer, eh? ;-) – Moshe Nov 9 '10 at 2:17
  • @Moshe: Java actually. This is code from a very large and complex applet, basically like a desktop Swing app except that it runs in the browser. :) – Bobby Tables Nov 9 '10 at 2:24
  • I though that MDI is a .NET term. – Moshe Nov 9 '10 at 3:05
  • @Moshe: Nah, it's generic (en.wikipedia.org/wiki/Multiple_document_interface). – Bobby Tables Nov 9 '10 at 4:57

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.

  • 1
    What about a second person? – daviewales Jun 11 '14 at 17:47

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.