Before and after

Python inside a design document

The common case: a function pasted into Word between two paragraphs of explanation. On the left is the extracted document text; on the right is what comes back.

The retry helper below wraps each
outbound request and logs failures
before re-raising them:

def fetch_with_retry(url, tries=3):
    for attempt in range(tries):
        try:
            return requests.get(url)
        except requests.Timeout:
            logging.warning("timed out")
    raise RuntimeError("exhausted")

If every attempt fails, the caller
sees the last exception.

1
2
3
4
5
6
7

def fetch_with_retry(url, tries=3):
    for attempt in range(tries):
        try:
            return requests.get(url)
        except requests.Timeout:
            logging.warning("timed out")
    raise RuntimeError("exhausted")

Note what stayed prose. "If every attempt fails, the caller sees the last exception." begins with a capital, ends with a full stop and reads as ordinary English from start to finish, so it is never in contention.

Java, C++ and JavaScript

The same document continues with three more listings, and each is identified without difficulty — a block of this length leaves far too many fingerprints to be mistaken for another language. How certain identification usually is.

1
2
3
4
5
6
7
8
9

public class RetryClient {
    private static final int MAX_TRIES = 3;

    public String fetch(String url) throws IOException {
        for (int i = 0; i < MAX_TRIES; i++) {
            try { return client.send(url); }
            catch (IOException e) { System.out.println("retry"); }
        }
        throw new IOException("exhausted");
    }
}

1
2
3
4
5
6
7
8
9

#include <iostream>
#include <string>

int main() {
    std::string url = "https://example.com";
    for (int i = 0; i < 3; ++i) {
        cout << "attempt " << i << endl;
    }
    return 0;
}

1
2
3
4
5
6
7
8
9

const fetchWithRetry = async (url, tries = 3) => {
  for (let i = 0; i < tries; i++) {
    try {
      const res = await fetch(url);   // may reject
      return await res.json();
    } catch (err) {
      console.warn(`attempt ${i} failed`, err);
    }
  }
};

Cases it deliberately leaves alone

Equally important, and rarely shown. None of the following produces a code block, which is the correct result in each case.

Sentences containing code punctuation

"The result (see Figure 3) was conclusive." and "The ratio of x to y was 3:1 in every trial we ran." both contain the punctuation that pushes lines upward, and both are firmly prose once the sentence penalty applies.

Numbered headings and bullet lists

"2. Methodology (revised)" and "• Budget: $4,500" end in the right characters and are short on stopwords, but they read as a numbered list of instructions and carry no code with them, so they stay prose.

Aligned tabular text

A three-column staff table with names and dates is often set in a monospaced font, which on its own looks a lot like a listing. It is still left alone, because there are no keywords, no brackets and no code punctuation to go with it — which is precisely why no single piece of evidence is allowed to decide on its own.

A one-line snippet inside a sentence

"You can print with System.out.println("hello"); in Java." is not turned into a code block. It is a sentence that mentions code, and lifting it out would break the paragraph. Inline snippets are a different problem from code blocks and are not attempted.

Shell transcripts and log output

$ npm install followed by installer output is not one of the named supported languages. Depending on its shape it is either left as prose or picked up as an Unknown block. Neither is wrong — it simply is not Python, C++, Java or JavaScript.