4

A lot of time when I'm writing a Programming Puzzles & Code Golf challenge, I need to incorporate multiline blocks of code

like
this

into my sentences.

Many times, it's simplest to have them at the very end of a sentence. For example, this scenario is easy to envision:

If the input is 1, the output of your program should be

sample output 1

If the input is 2, the output of your program should be

sample output 2

The problem is that there are supposed to be two complete sentences here, but there are no periods!

One obvious solution is to add periods after the code blocks:

If the input is 1, the output of your program should be

sample output 1

. If the input is 2, the output of your program should be

sample output 2

.

But this just looks weird.

Another solution is to add 'this:' after the 'be', and forgo the periods:

If the input is 1, the output of your program should be this:

sample output 1

If the input is 2, the output of your program should be this:

sample output 2

(I don't think it's grammatically correct to just put the colon after 'be' but I may be wrong.)

This seems more complete, but is still rather awkward with the 'this'es, and won't always work if the sentence is more complex. e.g.

The program

example code A

runs better than

example code B

[comma?] but both are worse than

example code C

[period?]

So what's the best way to do this - specifically on Stack Exchange where it's impossible to put a period directly after a code block?

Improve this question
5
  • 1
    Maybe more relevant on some meta site? Idk, I like your stuff on PPCG though :) EDIT: I personally like If the input is 1, the output of your program should be:
    – Caleb
    Jul 17, 2015 at 2:32
  • Just do the best you can, given the tools you have. If you ever publish a book, the editors will likely have some style suggestions to address the issue.
    – Hot Licks
    Jul 17, 2015 at 3:27
  • @HotLicks achewood.com/index.php?date=07102002
    – Caleb
    Jul 17, 2015 at 3:36
  • Understand that the "rules" for punctuating sentences were developed before there was an Internet, and, for that matter, before there were computers. At best there were rules for embedding "block quotes" in your text, but these were not anticipating the need to embed code segments. In another 50 years perhaps a "standard" scheme will be worked out (but of course by then it will be irrelevant, as the issue will become embedding thought waves or some such).
    – Hot Licks
    Jul 17, 2015 at 11:28
  • And far more important than adhering to some rules is producing a result that conveys your intend and that your reader will be able to understand, without too many Ouija consultations.
    – Hot Licks
    Jul 17, 2015 at 14:01

1 Answer 1

Reset to default
1

Consider, if you will, a hypothetical Manners SE site, where someone posts:

If the person you're talking to gets mad, your response should be

don't get mad!

But if they seem happy, your response should be

I'm glad you're happy!

This works because it's a more clear way of formatting

But if they seem happy, your response should be, "I'm glad you're happy!"

This sentence, in turn, is valid because the exclamation point within the quote also counts for the main sentence (I think?).

By analogy, a block of code's natural termination point, in this scenario, not only signals the end of the code block, but of the sentence containing the code block.

This is my theory. In the absence of a Stack Exchange style guide, it should be open to the individual's reasonable taste.

Improve this answer
2
  • So you're saying that each code block has it's own intrinsic period? What if you want to include multiple blocks in a sentence, as in my last quoted example? What if you want to end the sentence with a question or exclamation mark? (Note that adding punctuation in the code block, as in your "I'm glad you're happy!" example, would be a big no no because then it will be interpreted as part of the code.)
    – Calvin's Hobbies
    Jul 17, 2015 at 2:51
  • @Calvin'sHobbies Yes, I think a code block has an intrinsic period. For commas or question marks, to keep to my theory, you would front-load all commentary... something like "Here are my three options... which is the best one?" followed by three code blocks.
    – Caleb
    Jul 17, 2015 at 2:55

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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