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 (eg 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 (eg 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.
