Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

closed as primarily opinion-based by MichaelT, Kilian Foth, GlenH7, jwenting, gbjbaanb May 13 at 18:28

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

1  
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
add comment

9 Answers

up vote 21 down vote accepted

Full stop is for separating sentences. If a comment consists of just one sentence surrounded by code, then full stop is not necessary. 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; 
}
share|improve this answer
2  
+1. This looks so much like my commenting style it gave me a false deja vu. :) –  Bobby Tables Nov 9 '10 at 2:12
11  
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
1  
<joke>Wouldn't it be better to check for exceeding int boundaries?</joke> –  Yar Nov 9 '10 at 8:20
1  
@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
5  
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
show 4 more comments

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

share|improve this answer
    
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
1  
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
    
Yes, i think we agree with each other without knowing. ;) –  LennyProgrammers Nov 9 '10 at 14:41
add comment

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

share|improve this answer
1  
How about text messages? –  Moshe Nov 9 '10 at 2:38
2  
@Moshe, text messages are hardly proper English. –  DominicMcDonnell Nov 9 '10 at 2:54
2  
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 –  DominicMcDonnell Nov 9 '10 at 21:31
    
I nu wot u ment im wiv u all da way –  cjmUK Nov 10 '10 at 11:52
add comment

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.

share|improve this answer
    
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. –  Anna 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
add comment

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.

share|improve this answer
add comment

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?
share|improve this answer
add comment

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.
share|improve this answer
    
.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
add comment

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.

share|improve this answer
    
What about a second person? –  daviewales Jun 11 at 17:47
add comment

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.

share|improve this answer
add comment

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