Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How to structure a sentence containing long code examples?

+2
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/16512. It is licensed under CC BY-SA 3.0.

0 comment threads

4 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+1
−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)

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/16526. It is licensed under CC BY-SA 3.0.

0 comment threads

+2
−0

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."

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/16514. It is licensed under CC BY-SA 3.0.

0 comment threads

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »