1

I am writing a technical document in which I need to intersperse examples into paragraphs. For example I have a sentence like below:

For example, rather than the following code example:

//This is some bad code

We should use this code example instead:

//This is some good code

This reads as one sentence: "Rather than [thing A], we should do [thing B]." My issue is I'm not quite sure of the proper way to handle punctuation or capitalization. If this is a single sentence, I would think there should be a comma after the bad code example and period after the good code example, but it just seems out of place to have them. I'm also not sure if the colons are appropriate (though again, it looks weird without them). Also, I would think that "We" should not be capitalized, because it is a continuation of the above sentence, but that again, it doesn't look right.

What's the proper way to handle this kind of thing?

  • You seem to make a rod for your own back. Why not compose it in a way that the example does not appear mid-sentence? – WS2 May 5 '16 at 17:32
  • @WS2 Can you give an example? I wasn't able to come up with an alternate wording that didn't feel contrived and awkward. – ewok May 5 '16 at 17:34
1

Below is a suggestion as to how you might rephrase the text to avoid the problem.

That which follows are examples of bad and good code respectively. One should substitute the latter for the former:

//This is bad code; //This is good code.

0

I think the way you punctuated and capitalized your example is probably right as it stands. Putting a period at the end of a code sample is problematic because there is no good way to separate it from the code. That means there is no period at all at the end of that sentence, but sometimes there must be compromises.

If this is to be published in a journal, the journal's house style may specify how this is to be handled.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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