This section provides an overview of how to present information about computer programs.

See Computing style resources for guides that go into much greater detail.

Snippets

Sometimes a few lines of code (a snippet) may be included in the body of a document. A computer program:

  • is generally written as plain text
  • often uses indenting to set off and align its components
  • may use indenting as part of the syntax (e.g. Python).

Each language has its conventions, such as use of capitals (PRINT vs Print vs print), indentation and spacing.

In general:

  • When presenting code, use a monospaced font, because it maintains indenting and alignment of columns; always keep the indenting

#! /usr/bin/python
sentence = raw_input ("Please type a sentence and hit Enter: ")

# Use spaces to split the sentence into an array of words
words = sentence.split(' ')

# Put unique words into the variable uniq
uniq = []
for item in words:
    if item not in uniq:
        uniq.append(item)

# Write out the unique words
print ("------------------------")
print ("The words you used were:")
for i in uniq:
    print i

  • A variable or keyword referred to in running text should keep the same font as in longer examples, rather like a variable in a mathematical discussion
In the example above, raw_input is a function, not is a reserved word, and our sentence is stored in the variable sentence.
  • Colour or font effects (e.g. bold) can be used to highlight components of the code to aid discussion. For example, reserved words might be written in bold. Tune such usages to the nature of the discussion – don’t clutter the text with font effects unless they add value.
  • Avoid using quotation marks to highlight or introduce terms when discussing code, because code often uses these marks itself.
  • If using a word processor, take care to avoid autocorrection introducing errors. For example, 3 full stops should not become an ellipsis character, quotation marks should not be made curly and 2 hyphens should not become an en rule. Automatic capitalisation may lead to inconsistent presentation of keywords and variables.
  • Set blocks of code off – use block indents (like block quotes), boxes or some other suitable mechanism.

Rules about writing correct, well-presented code are beyond the scope of this manual, but should be followed.

Program listings

If a program listing must be included, it should be in an appendix unless it is very short and discussed in some detail in the main text (e.g. in a computing textbook). Again, a monospaced font is generally best.

Pseudocode and algorithms

Pseudocode is used to describe an algorithm in a way that is not specific to any one programming language. Some pseudocodes are relatively simple:

IF BankBalance < 0 THEN
     Display overdrawn message
ELSE
     Display not yet in debt message
ENDIF

Some pseudocodes follow a detailed set of conventions and use specialist symbols – and may not use monospace fonts:

for i ← 1 to n do
        ⋮                               ▷    the body of the loop goes here
end for

[Reserved words are written in bold, variables in italic; the leftwards arrow is used for assignment, and the rightwards triangle, like a flag, indicates a comment.]

Find and follow the pseudocode conventions of the publication you are writing for. See Computing style resources.

Program output

Program output should in general be presented verbatim, unless being summarised. For a graphical program, a screen capture (possibly annotated) may be best. If the output is text written to a terminal or file, consider using a monospaced font:

We can experiment with different inputs to our little program:

$ ./myexample.py
Please type a sentence and hit Enter: That 'that' that that that refers to should be a 'which'.
------------------------
The words you used were:
That
'that'
that
refers
to
should
be
a
'which'.

We see that That, that and 'that' are all seen as different words.

Using the monospaced font allows less ambiguous discussion of terms from the output (like that).