Post History

Source: https://writers.stackexchange.com/a/16526
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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)`

Original score: 1