31

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?

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

9 Answers 9

36

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; 
}
12
  • 4
    +1. This looks so much like my commenting style it gave me a false deja vu. :) Commented Nov 9, 2010 at 2:12
  • 30
    No, full stop is for marking the end of sentences. It is irrelevant whether you have one or several.
    – Rook
    Commented Nov 9, 2010 at 2:59
  • 2
    <joke>Wouldn't it be better to check for exceeding int boundaries?</joke> Commented Nov 9, 2010 at 8:20
  • 2
    @Yar: an average is always between a and b, which by definition are always within the boundaries, right? ;)
    – mojuba
    Commented Nov 9, 2010 at 8:24
  • 9
    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? Commented Nov 9, 2010 at 16:49
34

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

5
  • 2
    How about text messages?
    – Moshe
    Commented Nov 9, 2010 at 2:38
  • 5
    @Moshe, text messages are hardly proper English. Commented Nov 9, 2010 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
    Commented Nov 9, 2010 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 Commented Nov 9, 2010 at 21:31
  • I nu wot u ment im wiv u all da way
    – cjmUK
    Commented Nov 10, 2010 at 11:52
20

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

5
  • 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? Commented Nov 9, 2010 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
    Commented Nov 9, 2010 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? Commented Nov 9, 2010 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
    Commented Nov 9, 2010 at 13:51
  • 1
    Yes, i think we agree with each other without knowing. ;) Commented Nov 9, 2010 at 14:41
9

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.

2
  • 2
    Periods are for the end of a sentence. Comments are not necessarily full sentences. Commented Apr 14, 2017 at 14:39
  • 1
    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? Commented Apr 17, 2017 at 23:48
6

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.

4
  • If you're using question marks, do you understand your own code?
    – Moshe
    Commented Nov 9, 2010 at 3:14
  • @Moshe: Those are usually in TODOs when I may not yet fully understand my own code.
    – Adam Lear
    Commented Nov 9, 2010 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
    Commented Nov 9, 2010 at 10:43
  • 1
    In working with large projects and many collaborators i often find those questioning comments the most important. Commented Nov 9, 2010 at 14:44
5

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?
1

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.
4
  • .NET developer, eh? ;-)
    – Moshe
    Commented Nov 9, 2010 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. :) Commented Nov 9, 2010 at 2:24
  • I though that MDI is a .NET term.
    – Moshe
    Commented Nov 9, 2010 at 3:05
  • @Moshe: Nah, it's generic (en.wikipedia.org/wiki/Multiple_document_interface). Commented Nov 9, 2010 at 4:57
1

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
  • 1
    What about a second person?
    – daviewales
    Commented Jun 11, 2014 at 17:47
1

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.