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?

Moshe
  • 5,022
  • 2
  • 30
  • 49
  • 2
    SOmetimes i do and sometimes i don't. It depends on the comments and what makes it easy to read. – Tim Nov 09 '10 at 04:07

9 Answers9

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; 
}
mojuba
  • 5,583
  • 2
  • 24
  • 32
  • 4
    +1. This looks so much like my commenting style it gave me a false deja vu. :) – Bobby Tables Nov 09 '10 at 02:12
  • 30
    No, full stop is for marking the end of sentences. It is irrelevant whether you have one or several. – Rook Nov 09 '10 at 02:59
  • 2
    Wouldn't it be better to check for exceeding int boundaries? – Dan Rosenstark Nov 09 '10 at 08:20
  • 2
    @Yar: an average is always between a and b, which by definition are always within the boundaries, right? ;) – mojuba Nov 09 '10 at 08:24
  • @Rook: that's a programmer's view really :) Historically, full stop plus capitalization was for visually separating the sentences. The last full stop in a paragraph was just for consistency. – mojuba Nov 09 '10 at 08:26
  • @Rook: for example there is no full stop in titles, because it is visually separate anyway – mojuba Nov 09 '10 at 08:35
  • @mojuba - Take a book that deals with orthography and spelling rules for the precise definition. Yes, it goes in titles and sub-titles too, if they are in one row, one behind the other, or if they're in the same row as the continuing text. – Rook Nov 09 '10 at 13: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? – CodexArcanum Nov 09 '10 at 16:49
  • On a side note, I'm trying to stop duplicating code with comments. In this case I would remove the first line of the header and called the function 'the_average' (if average itself is a reserved word) or even average_of_two_numbers if it really is only for 2 numbers only. If it allowed more inputs, have the code say that, e.g. average_of_two_or_more_numbers. In this case I might keep the stuff about "irrelevant result" in the comment because I'm not going to call the method average_of_two_or_more_numbers_may_return_irrelevant_result_if_first_larger_than_second ow my fingers are cramping ;) – Michael Durrant May 01 '12 at 21:30
  • For me, it just looks odd that a sentence doesn't end with a full stop. – emeraldhieu Mar 05 '18 at 04:14
  • 1
    @mojuba (a+b)/2 by definition will NOT always be within the boundaries. Division by 2 is only done after the addition of the two numbers. That means the intermediate step i.e `a+b` can overflow. [See this](https://www.geeksforgeeks.org/compute-average-two-numbers-without-overflow/) to understand how this can be avoided. :) – GiriB Mar 07 '19 at 07:16
  • @GiriB I knew one other one-liner solution but that one is also neat, thanks! – mojuba Mar 07 '19 at 11:30
33

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

Dominique McDonnell
  • 1,273
  • 11
  • 14
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 ;-)

Rook
  • 19,861
  • 9
  • 53
  • 96
  • 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 09 '10 at 08: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 09 '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 09 '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 09 '10 at 13:51
  • 1
    Yes, i think we agree with each other without knowing. ;) – LennyProgrammers Nov 09 '10 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.

quickly_now
  • 14,822
  • 1
  • 35
  • 48
  • 2
    Periods are for the end of a sentence. Comments are not necessarily full sentences. – John B. Lambe Apr 14 '17 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? – quickly_now Apr 17 '17 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.

Adam Lear
  • 31,939
  • 8
  • 101
  • 125
  • If you're using question marks, do you understand your own code? – Moshe Nov 09 '10 at 03:14
  • @Moshe: Those are usually in TODOs when I may not yet fully understand my own code. – Adam Lear Nov 09 '10 at 03: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 09 '10 at 10:43
  • 1
    In working with large projects and many collaborators i often find those questioning comments the most important. – LennyProgrammers Nov 09 '10 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?
Dan Rosenstark
  • 2,344
  • 1
  • 20
  • 20
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.
Bobby Tables
  • 20,516
  • 7
  • 54
  • 79
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

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.

Matt DiTrolio
  • 459
  • 2
  • 10