How to structure a sentence containing long code examples?

Question

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sentence containing "before" and "after" examples which appear in (potentially multi-line) vertical blocks of their own. As a result, I am unsure as to whether the middle of the sentence should be capitalized. Additionally, a suggestion was made on ELU SE that removal of colons leading the code blocks may be preferable. I have presented an example of this below as well.

---

With capitalization

Hence, the following code:

camera.start_recording('foo.h264', quantization=25)

Should be replaced with:

camera.start_recording('foo.h264', quality=25)

---

Without capitalization

Hence, the following code:

camera.start_recording('foo.h264', quantization=25)

should be replaced with:

camera.start_recording('foo.h264', quality=25)

---

Without capitalization or colons

Hence, the following code

camera.start_recording('foo.h264', quantization=25)

should be replaced with

camera.start_recording('foo.h264', quality=25)

---

My instinct suggests the second or third examples are preferable, but I'd be interested to learn of any style rules addressing this. For that matter, if there is a better way of structuring such examples which avoids these issues altogether, I would be most interested!

Should I capitalise "or" between examples? was the most relevant question I could find to this one (and indeed was the corner of SE where I first posed this query, before being made aware of Writers), and I tend to agree with its reasoning that the lowercase version is preferable. Unfortunately the best suggestion in its answer (to use a bullet list of examples) doesn't really lend itself to potentially large blocks of code.

Answer 1

In my opinion, any answer looks messy. One "sentence" with capitals halfway through bugs me; so does a line starting without a capital.

Personally, I would restructure the entire thing to avoid the issue entirely:

Example 1

Currently, line 57 of camera.py looks like this:

camera.start_recording('foo.h264', quantization=25)

In this line, the parameter quantization needs to be replaced with quality, giving us this:

camera.start_recording('foo.h264', quality=25)

Example 2

Look at Figure 1 below. Our code currently contains line (1); we need to replace it with line (2).

(1) camera.start_recording('foo.h264', quantization=25)

(2) camera.start_recording('foo.h264', quality=25)

Figure 1 - Two versions of line 57 of the code in camera.py

(Obviously I don't know your code file name, line numbers, or programming language. Substitute where necessary. "camera.py" can be replaced with Example 1 if you're taking that route.)

Answer 2

I like the third version, without colons, because the visual break and the code formatting makes it clear that this is a new "clause," or thought, and the piece of code is not a grammatically correct full sentence. Since you are continuing one sentence over several breaks, I wouldn't use capitals.

I think Watercleave has another good solution if you can't settle on any combination of punctuation and capitalization.

Answer 3

I approach code in text in the same way I approach dialogue: the code is a quotation from another "speaker", so I set it off from the surrounding text. Since it is not spoken language, I do not use the conventions for spoken language (same font, quotation marks, etc.), so as to cause no confusion, but the conventions for displaying code (monospaced font, line numbering, blockquote, etc.), but I integrate it syntactically in the same way, for example by using colons and continuing sentences with lowercase letters.

Therefore, in my opinion, your second example is best.

Example:

When five year old Maude said: "I am not interested in horse riding," what she actually meant was: "I am afraid of horses".

Similarly:

Hence, the following code: camera.start_recording('foo.h264', quantization=25), should be replaced with: camera.start_recording('foo.h264', quality=25).

Of course you must not put commas inside the code quote, as English rules require for dialogue ('riding,"'). When you put your code snippets on separate lines for better readability, the syntax, capitalization and punctuation remain the same.

A good practice is to print the whole script in an appendix, and thoughout the text use the same line numbers as in that appended script. You can then refer to code by line numbers:

In line 21, quantization must be replaced by quality:

21 camera.start_recording('foo.h264', quality=25)

Answer 4

Do the simplest thing that works, which in this case is example 3. The rules of sentence structure don't really cover these kinds of things. That is a defect of the rules of sentence structure, not of the examples themselves.

Remember that the first rule is clarity. Grammar rules and style guides exist to codify the practices that usually produce the clearest and least ambiguous result. They are a good guide most of the time. But these rules are the servants of clarity, not its master, and in some cases clarity will demand something that these rules cannot account for.

Doing something more convoluted or complex in order to stay onside with a grammar rule or a style guide is putting the horse before the cart. As George Orwell said, "Break any of these rules sooner than say anything outright barbarous."

Answer 5

I have to document code use on occasion and I prefer a clear cut structure, so I would simply say:

The following code camera.start...

should be replaced with: camera.start_...

Programmers won't care about your grammar choices, they will only need to know what code to use. Just my two cents worth. Thanks