# punctuation after code block convention

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?

-

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.

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

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
``````
-
+1 for the capital letter after a colon link and for good alternatives. – Matthew Adams Sep 1 '12 at 20:13

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.

-
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