Practices to rely on (and avoid) in pseudocode.
If the computational procedure being described in the pseudocode is parameterized by one or more input values, these inputs must be declared, with the relevant types, at the start of the pseudocode—e.g., in a section labeled “Inputs” or “Given”.
Well-known mathematical constants such as $\pi$, $\phi$, and $\text{e}$ must be referenced symbolically, rather than using literal numeric values.
Constants and variables must be declared prior to or on first use, with the type included in the declaration.
Just as in programming code, “magic numbers” should be avoided in pseudocode. Do not include literal constants (other than $-1$, $0$, $1$, and other self-explanatory values) in the pseudocode, other than in the definitions of constants or variables.
Input, constant, and variable type declarations should not use Java-specific types; instead, prefer more general mathematical types (e.g., integer, real, Boolean) over Java primitive types. Similarly, prefer sequence, array, list, and set over Java implementation types.
While the order of declaration of variables, fields, and constants in Java (a type followed by a name) is familiar to C, C#, C++, and Java programmers, it may not be intuitive to non-programmers, or to programmers unfamiliar with the C-derived languages. Because of this, prefer a reversed declaration order of symbols in pseudocode: the name, followed by a colon, and then the type–e.g., “$x\text{: real}$”.
Arrays, lists, and sets must be clearly declared as such, preferably following the form “array of {type}”, or “{type} array”, rather than “{type}[]”. For example, “$V\text{: array of integer}$” can be used to declare $V$ as an array of integers.
Symbolic names of inputs, constants, and variables must be distinguished typographically from other text in the pseudocode. The mathematical convention of italicizing such symbols is preferred for this purpose. (Note that this distinction is implemented in $\LaTeX$ by default.)
While pseudocode must not be written in such a way that it can only be implemented in one programming language, there are a number of English words and phrases that are used as keywords in most programming languages; don’t hesitate to use them if they help make the logic of the pseudocode clear. For example, the following are often included in pseudocode, and are encouraged for pseudocode written in this bootcamp:
On the other hand, there are a few keywords in several programming languages that have alternatives in natural language that may be more clear to readers, and should thus be preferred to their programming equivalents when writing pseudocode. In particular, “otherwise” should be used in place of “else”.
To avoid confusion around assignment vs. equality comparison, pseudocode in this bootcamp must use a single equals sign ($=$) for equality comparison, and must use the $\gets$ (“gets”) operator for assignment.
The only exception allowed to this rule, if neither $\LaTeX$ notation nor HTML/XML entities are available, is to use “Let” (or if the writer’s chosen natural language is not English, then the local language equivalent of “Let”) with a single equals sign for assignment. For example, the following two statements are equivalent; the first is the form required in Markdown or HTML, while the second is an acceptable alternative otherwise.
Note that even when $\LaTeX$ is not available, the ← HTML entity or ← HTML/XML numeric entity may be used to produce the left arrow symbol (←) in Markdown or HTML content.
Do not mix multiple natural languages in the pseudocode for any single algorithm or other computational process. Of course, pseudocode can and should be written in the natural language most likely to be shared between the writer and the audience; muddying the waters by mixing languages can confuse the intended readers, and must be avoided.
When using mathematical notation, any symbols beyond those typically seen in second-year algebra, introductory analytic geometry, or introductory trigonometry must either be defined prior to use, or be annotated with a callout to a definition (e.g., in a footnote or separate page). More generally, when in doubt, favor explicit definition over assumption of shared understanding.
To refer to individual elements of an array, list, or sequence, the element indices should be written as subscripts, though brackets or parentheses are also permitted. For example, $x_i$ is preferred over x(i) or x[i]. (When $\LaTeX$ notation is not available, the HTML <sub>...</sub> element can be used for subscripts in Markdown or HTML content.)
Exponents should be indicated with superscripts when possible; otherwise, the ^ can be used to separate the base from the exponent in an expression. For example, prefer $a^b$ to a^b. (When $\LaTeX$ is not available, the HTML <sup>...</sup> element can be used for superscripts in Markdown or HTML.)
Prefer grammar and syntax borrowed from natural language and mathematical expressions to those of programming languages. In particular, even when using symbols, remember that you’re writing statements that must be read and understood by human readers. Those statements may employ a simplified grammar, like headlines in a newspaper, but they must still be understandable. Also, just as the appropriate syntax, capitalization, and punctuation can help a reader understand common written language, they should be used for the same purpose in pseudocode.
For example, when expressing an operation to be repeated for all values of $row$ between 1 and $rowCount$ (inclusive), prefer
- …
For each $row$ in $(1, 2, 3, \ldots, rowCount)$:
- …
to
- …
for $row = 1$ to $rowCount$
- …
Arguably, the second has a bit more room for misunderstanding. For example, is the step size 1, or some other increment? Is $rowCount$ an inclusive or exclusive bound? More subtly, the capitalization and punctuation in the first help the reader see clearly the logical separation between the iteration statement and its predecessor, and between the iteration conditions and the statements to be executed repeatedly under those conditions.
While a programming-language-style expression may be admirably unambiguous, it requires the reader to be familiar with the underlying language (or at least, a family of languages). So, an expression like the following is not acceptable in pseudocode written in this bootcamp.
- …
for ($row = 1$; $row <= rowCount$; $row$++):
- …
Do not use explicit multiline grouping constructs, such as the braces found in programming languages derived from C. Instead, use indentation and numbering or bullets to indicate structure, as described in “Formatting” (below).
Pseudocode must be formatted using an ordered (numbered) or unordered (bullet) list, with nested lists as appropriate. Use the indentation structure of nested lists to provide visual and logical structure to the pseudocode.
Use embedded $\LaTeX$ and code fragments as appropriate. However, when using $\LaTeX$ or code blocks, be sure to respect the current indentation of the enclosing list, so that key aspects of the list structure (e.g., the numbers used in an ordered list) isn’t broken.
Depending on the intended audience, additional explanatory text annotations may help the reader to understand the pseudocode. When considering the inclusion of such annotations, please follow these guidelines:
Prefer clarifying the pseudocode itself to including additional explanatory text.
An explanatory annotation must either be inline—i.e., accompanying the pseudocode statement it explains (e.g., in a parenthetical statement following the pseudocode statement)—or be included in a legend following the entire block of pseudocode.
Do not mix and match inline and legend annotations for the same block of pseudocode.
If using inline annotations, they must be distinguishable from the pseudocode itself.
If using inline annotations, the annotations must not break the structure of the pseudocode. That is, the indentation and numbering (if ordered lists are used) of the pseudocode statements must not be disrupted by the explanatory text accompanying the pseudocode statements.
If using a legend for explanatory annotations, an ordered (numbered/lettered) list must be used in the pseudocode, and the legend must reference steps by number.
The following example includes inline explanatory annotations with some of the statements. Each such annotation is written in parentheses immediately below the statement it explains, and follows the indentation structure of the pseudocode.