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

3 Answers

up vote 6 down vote accepted

You generally just drop the punctuation altogether.

The equation


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

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

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

You must log in to answer this question.

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