How to write good pseudocode

WritingPseudocode.md

How to write good Pseudocode

This is an unfinished list of remarks on how to write good pseudocode.

What is pseudocode?

Pseudocode is a loosely defined way of transmitting the concept of an algorithm from a writer to a reader. Central is the efficiency of this communication, not the interpretability of the code by an automated program (e.g., a parser).

Pseudocode is not code. There have been attempts (like this) to standardise pseudocode. This is a Bad Idea^TM. Pseudocode is not standardised for a reason: so that the writer has the freedom to use whatever needed to make it clear what he means.

Suggestions

• Use mathematical notation when applicable.

  Typically, mathematical notation is much easier to read than programming code. Compare for example abs(log(x**2)) to |log(x²)|. Also, some programming languages behave differently on some operators (like modulo in case of negative numbers), and using mathematical notation should be better defined. In addition to that, the link with the text around the algorithm will be more clear.

  This can go from relatively small changes, like above, to bigger ones, like using set builder notation and other fancier notations. The reader is supposed to be able to derive the complexity from that himself, if needed.

  The same applies to logic operators like ∧ (instead of e.g. &&). However, just to be clear: conditional statements (like if .. else ..) cannot be replaced by logical implication (→), which is a logical expression (not an algorithmic statement).

• Don't rely on programming language conventions.

  For example, consider a dictionary of keys and values on which in some language a method .lookup(k) is defined which gives either the value corresponding to key k or null if the key doesn't exist. Then we may be tempted to write the following pseudocode:

   v = dict.lookup(k)
   if v != null:
           print(v)
  

  However, you cannot assume your readers will know the conventions of that particular language (and how are they supposed to know what language you had in mind at the time of writing?). Instead, again, use mathematical notation:

  if ∃v: (k, v) ∈ dict:
      print(v)

• You shouldn't have to explain your pseudocode.

  Once you start explaining your pseudocode, you're doing it wrong. The sole use of pseudocode is to explain an algorithm. If you have to explain your explanation, you should use that second explanation instead.

• Pseudocode works better when strongly typed.

  Usually, you will already have defined the higher order types elsewhere in your article. For example, if you are writing about playing cards, you may have a set S of suits, R of ranks and C = S × R of cards. We can see types as sets of values, so these sets directly define the types of the objects in your pseudocode. And then it should be obvious to the reader that the following checks if all cards in the hand of the player are higher than the cards currently on the table:

  assume onTable ⊆ C, inHand ⊆ C
  let highestOnTable = max {r | (s,r) ∈ onTable}
  for (s, r) in inHand:
      if r ≤ highestOnTable return false
  return true

• Indent code blocks

  No matter how ugly you want to format your 'real' programs, in pseudocode it always works best to indent code blocks rather than surround them with curly braces (and indent them in a weird way or not at all). And of course, if you use indentation appropriately, curly braces are redundant.

• Use 'syntax' highlighting

  There are several packages that help you writing algorithms in (La)TeX. 'Syntax' highlighting aids the reader to quickly familiarise himself with the 'code'. Of course, a syntax highlighter presupposes some kind of idea of defined structure. Don't let it force you to write things in a certain way, though. If the package forces you to write a different 'code', use a different package. Clarity is most important.

Pseudocode is optimal for complex programs that are hundreds to thousands of lines in length.

Thanks