Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 155 Stack Exchange communities.

What is meta?
Here's how it works:
  1. Any Stack Exchange user can ask a question
  2. The community provides support, votes on ideas, and reports bugs
  3. Your voice helps shape the way Stack Exchange operates

What is the (/is there a) convention for putting punctuation after a block of code?

When you are writing up something that has math equations in it, I believe you are supposed to just put the punctuation in line with the equation, like the comma in this example:

"The equation

x=y+z ,                                                                       (1)

where x is something and y and z are other things, shows how to add."

This obviously doen't work when writing out code though, so what is the convention?

share|improve this question
up vote 6 down vote accepted

You generally just drop the punctuation altogether.

The equation

x=y+z

where x is something and y and z are other things, shows how to sum to values.

share|improve this answer
    
This is what I've been doing, but it just feels wrong, particularly when sentences don't have the ending period because of it... – Matthew Adams Sep 1 '12 at 18:09
3  
@MatthewAdams: I bet hanging sentences bother you as – Martijn Pieters Sep 1 '12 at 18:10
    
.... (ಠ⌣ಠ) .... – Martijn Pieters Sep 1 '12 at 18:12
    
Oh I see what you did there. (╯°□°)╯︵ ┻━┻ – Matthew Adams Sep 1 '12 at 18:22

If the language the code is written in supports line comments, you can use those to include punctuation.

The function

uint32_t reverse_bits(uint32_t n) {
    n = ((n >>  1) & 0x55555555) | ((n & 0x55555555) <<  1);
    n = ((n >>  2) & 0x33333333) | ((n & 0x33333333) <<  2);
    n = ((n >>  4) & 0x0F0F0F0F) | ((n & 0x0F0F0F0F) <<  4);
    n = ((n >>  8) & 0x00FF00FF) | ((n & 0x00FF00FF) <<  8);
    n = ((n >> 16) & 0x0000FFFF) | ((n & 0x0000FFFF) << 16);
    return n;
}
//,

which I've written just to illustrate the technique here, reverses the bits in an unsigned 32-bit integer.

It looks kind of wonky, though, so I usually just omit the punctuation after code blocks. But when the punctuation seems important, that's a way to include it without invalidating the code.

Another option is to start the line after the code block with the punctuation. Looks wonky too, especially if the punctuation is a full stop, but I've done that also.

share|improve this answer
    
I guess it seems like we just have to accept wonkiness. (I've almost done the comment one a couple times, but I think making code slightly more confusing for the sake of grammar is probably frowned upon on a coding site.) – Matthew Adams Sep 1 '12 at 18:29

I'm not sure there's any "right" way to do it.

I don't like the idea of including English-language punctuation in a code block; I think code blocks should stand on their own and not try to interact with the text around them, rather the reverse.

I try to structure the language around code blocks to include the code block, either by using a positional reference (e.g., "The following code:") and continue after the code block either by starting a new sentence, or finishing the previous one. It's legitimate to use a capital letter after a colon.

The following equation shows how to sum the values of y and z:

x = y + z

Or, if context allows: ← meta-colon

This equation shows how to sum the values of y and z:

x = y + z

We don't have the ability to number or name code blocks, so this seems like a good compromise. Sometimes it makes more sense to name a block by filename or function, though:

The Summing Equation demonstrates how to sum the values of y and z. Both y and z can be values of any type. To clamber up that slim shaft without dragging Ja down and precipitating both to the same doom from which the copper-colored one was attempting to save me seemed utterly impossible, and as I came near the spear I told Ja so, and that I could not risk him to try to save myself.

Summing Equation

x = y + z
share|improve this answer
    
+1 for the capital letter after a colon link and for good alternatives. – Matthew Adams Sep 1 '12 at 20:13

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .