Constant Width Formatting Explained
The style does not change what a word means. A keyword set in constant width is still the same keyword. The formatting only tells the reader that the word belongs to a program.
Why Some Words Look Different
When you read a programming book or tutorial, you will notice that some words look different from the surrounding text. A variable name, a function name, or a keyword often appears in a fixed-width typeface. The source calls this style constant width formatting. It is a visual signal that the marked text is part of a program or refers to something a program uses.
What do you think happens?
Which words in this sentence should be set in constant width?
Reveal answer
circle_area and return
circle_area is a function name and return is a keyword, so both are program elements. The words the, function, value, and using are ordinary prose and stay in the normal typeface.
What Constant Width Marks
Constant width formatting is used for program listings and for referring to program elements within paragraphs. In both cases the style tells the reader that the characters are literal program text rather than ordinary words.
The source describes program elements broadly. When a program element is mentioned in a paragraph, it is set in constant width. The kinds of items covered include the following.
- variable and function names
- data type names
- statements and keywords
- databases
- environment variables
- commands
- module and package names
The list mixes two origins. Some items are things you write yourself, such as variable and function names. Others are defined by the language or the environment, such as keywords and data type names. Constant width does not distinguish between these origins. It only marks that the item is a program element.
The style does not change what a word means. A keyword set in constant width is still the same keyword. The formatting only tells the reader that the word belongs to a program.
Two Uses of the Style
Constant width appears in two situations that differ in scope. A program listing is a block of code shown as it would be written in a file. A reference within a paragraph is a single name or term that sits inside a sentence of normal explanatory prose. The diagram below contrasts how the style behaves in each case.
In both cases the style marks literal program text. The difference is how much text is marked and what happens to the surrounding words.
Tracing a Sentence Word by Word
Suppose you are writing a sentence about Python. Read it one word at a time and ask what each word is. In the sentence below, only two words name program elements: math is a module name, and sqrt is a function name from that module. The other words are ordinary explanation.
The sentence is: The math module provides sqrt for computing square roots.
Only math and sqrt are set in constant width. The word module is ordinary here because it describes the kind of thing math is, not a specific name in the program. The source explains that a module name such as math, when written in prose, tells the reader that the word names a real module rather than a general idea about mathematics.
Deciding Whether a Word Gets Constant Width
When you are unsure about a word, you can work through a short sequence of questions. The flowchart below shows the decision for one word in a sentence.
- 1Take one word from your sentence and ask whether it is a literal program element.
- 2Check whether it is a variable name, function name, keyword, data type, command, module name, or package name.
- 3If it is, set it in constant width when you mention it in prose.
- 4If it is an ordinary idea or a description, leave it in the normal typeface.
- 5Repeat for each word in the sentence, then reread the paragraph to check that only literal program elements are marked.
Mistakes Writers Make
Common mistake Marking every technical-sounding word
What it looks likeSetting the word algorithm in constant width in a sentence that describes an idea rather than a program element.
Why it failsThe source says to use the style for literal program elements, not for ordinary words that merely sound technical.
Do this insteadMark only names, keywords, commands, modules, packages, and similar literal elements.
Common mistake Believing constant width changes what a word means
Why it failsThe style does not change meaning. It only signals that the text is part of a program or refers to something a program uses.
Do this insteadTreat constant width as a signal to the reader, and keep the meaning of the word the same.
Common mistake Setting the whole sentence in constant width when only one element is mentioned
What it looks likeWriting an entire explanatory sentence in the fixed-width style to mention the keyword return.
Why it failsInside prose, constant width applies to the individual name or term. The surrounding sentence stays in the normal typeface.
Do this insteadMark only the element itself, such as return, and leave the rest of the sentence in normal text.
Common mistake Forgetting commands, modules, and packages
What it looks likeMentioning the module math in a sentence about imports without any special formatting.
Why it failsThe source states that commands and module and package names are also set in constant width when mentioned in prose.
Do this insteadCheck each sentence for commands, module names, and package names as well as variables, functions, and keywords.
Practice Your Decision
Read this sentence and decide which words belong in constant width: The math module has a function named sqrt, and you call it with a number to get its square root.
Hints
- Go through the words one at a time and ask whether each is a literal program element.
- Check the list of kinds: variable and function names, data type names, keywords, commands, module names, and package names.
- A word that only describes an idea, such as square root, stays in the normal typeface.
Key Takeaways
- Constant width formatting marks program listings and literal program elements mentioned in prose, such as variable and function names, keywords, data types, commands, and module and package names.
- In a full listing, the whole block of code is set in constant width so its spacing and line breaks can be read as written. In prose, only the individual element is marked.
- The style signals that text is literal program text. It does not change what a word means.
- To decide whether a word gets constant width, ask if it names a literal program element. If it is an ordinary idea or description, keep it in the normal typeface.