2

I often write documentation related to code and it is normally in a similar format to the following:

You will be able to run this code:
     <code>
        <moreCodeyStuff>
            ...
        </moreCodeyStuff>
     </code>
And then what you want to happen will happen.

My question is, should the and after the code block be capitalised? The entire block (including the text before and after the code) seems like it is a single sentence but doing an and without a capital letter doesn't seem correct.

Should the and be capitalised or not? Maybe I am just structuring this kind of block in the wrong way.

closed as primarily opinion-based by Jason Bassford, Dan Bron, Jim, Robusto, Scott Nov 4 '18 at 2:39

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 1
    Unless you are following a style guide (in general or of your company) there is nothing that determines how this should be done. Personally, I would say if you use a colon above, start a new sentence below. But that's only my opinion. – Jason Bassford Nov 2 '18 at 9:07
  • If code isn't read like a sentence, you should take a different strategy. In math you can read almost any equation like a sentence, so there is style (and answer below) for that. There's more of a habit in coding to put readable segments inline (e.g., "You can use x.length > y to test..."), but offset multiline code rarely is. The idea is that people popping out of your codeblock would still track correctly that they're in a sentence. – jimm101 Nov 2 '18 at 12:30
3

It is really a matter of opinion and house/journal style. However the way out for the purist is to avoid the issue by starting a new sentence if possible. This will also remove an interruption that might make the argument more difficult to follow. Here it's easy: just remove the "and" and start a new sentence with "Then".

(There is a problem with this approach — finishing the first sentence properly. Here you may have to modify the first sentence to refer to "the code that follows")

2

Different journals may do this in different ways. Many journals, such as ACM journals, typically put code and pseudocode into a figure, and not insert it into text.

If you are doing this to submit to a scientific journal, look at their style guide (assuming they have one that's online). And if it isn't treated in their style guide, look at some published articles in the journal and see how they treat code.

Very short sections of code could reasonably be included in the text, in which case you should decide whether the following text is part of the same sentence (in which case you should not capitalize) or not (in which case you should capitalize.

1

Scientific papers often follow the following format:

[English Text 1]
[Mathematical Equation]
[English Text 2]

The English Text 2 paragraph often continues to describe the equation with the word 'where'. In that case, they do not capitalise because the first sentence in the paragraph is not a full sentence.

See this example below:

enter image description here

So I would say that if the sentence grammatically makes sense to stand on its own, then capitalise it. But if it relies on having the code as a subject in the sentence, as in the case of the scientific papers, then don't capitalise it.

  • That's math, not code. Some scientific journals treat them differently (and some don't). – Peter Shor Nov 2 '18 at 12:29

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