5

I need to typeset the pseudocode of several pieces of code in latex. I found in this answer a good overview of the three main packages available to render pseudocode. In the following I will adopt the algpseudocode package that seems to be the most handy and complete one (imho). However, there are a number of details and best practices that I do not know and I could not find a satisfying answer. My goal is to achieve the best possible readability of the pseudocode (algorithms can be tricky on their own, no reason to make them even harder).

  1. Consider a single line of pseudocode. All its content (except comments) is usually rendered in math mode (even in the examples from the documentation manual). Is this the right choice from a typographical point of view? If so, I have an issue with variable names: if I use one letter variables (i, j, k, ...) everything is fine, but it gets awful when I need to render variable names with more than one letter (whenever is possible I try to use variable names with only one letter, but sometimes more descriptive names are needed for the sake of clarity). My current solution is the following:
\algnewcommand{\Var}[1]{\mathit{#1}}

\begin{algorithmic}
    \State $\Var{my\_var} \gets 1$
\end{algorithmic}

However, it is not perfect and I cannot use it outside of math mode to render the name of a variable (so that it is printed with the same style as in the pseudocode).

  1. Choose camelCase or snake_case for variable names? In the case of snake_case, how to correctly render the underscore?

  2. Roman or italic for variable names?

  3. When calling a function with more than one parameter, is the spacing inserted after the comma right?

\begin{algorithmic}
    \State $\Call{MyFunc}{arg1, arg2, arg3}$
\end{algorithmic}
  1. Since each line of code is rendered in math mode one may think that using math symbols is preferred whenever possible... however I'm not so sure this is always the best choice. One such case that often happens in my pseudocode is the following, which one do you think is more suitable? Why?
\algnewcommand{\In}{\mathbf{in}}

\begin{algorithmic}
    \ForAll{$i \in \{1, \ldots, n\}$}
        \State ...
    \EndFor
    \ForAll{$i \In 1, \ldots, n$}
        \State ...
    \EndFor
\end{algorithmic}
  1. Is there a handy why to refer to a block (i.e., many consecutive lines) of code? Something that provides the same result as the following (possibly requiring less code):
\begin{algorithmic}
    \For{$i = 1,2$} \label{algblock-start:for-loop}
        \State ...
    \EndFor \label{algblock-end:for-loop}
\end{algorithmic}
At lines \ref{algblock-start:for-loop}--\ref{algblock-end:for-loop} ...
  1. How to typeset "special" values like null, true and false? My current solution is to use mathbf:
\algnewcommand{\Null}{\mathbf{null}}
\algnewcommand{\True}{\mathbf{true}}
\algnewcommand{\False}{\mathbf{false}}
  1. [UPDATE] How to typeset the initialisation of common data structures such as arrays, hashmaps, queues and so on? At the moment I do the following:
\begin{algorithmic}
    \State $\Var{my\_array} \gets \Call{Array}{\Null}$
    \State $\Var{my\_map} \gets \Call{HashMap}{\Null}$
    \State $\Var{my\_queue} \gets \Call{Queue}{\Null}$
\end{algorithmic}
1
  • Actually, question 2/7/8 are style choices and maybe more suitable somewhere else.
    – user202729
    Feb 3 at 11:59

1 Answer 1

2
+50
  1. There are several ways to make a command like \Var work in and outside of math mode.

    \algnewcommand\Var[1]{\mbox{\itshape#1}}
    \algnewcommand\Var[1]{\ensuremath{\mathit{#1}}}
    
  2. Camelcase vs snakecase is a matter of taste, of community, etc. Long variable names are often not very readable in the context of an algorithm. Single letters or words are usually enough. If you really need long variable names, then it is maybe better to use syntax-highlighting of lstlisting or other packages: Write your algorithm in a common programming language, but leave out unnecessary syntactic elements (so it will not compile). E.g., some people use Python-like algorithms, with Python high-lighting.

    If you want to use underscores in variable names, you can use something like

    \algnewcommand\Var[1]{\mbox{\ttfamily\detokenize{#1}}}
    ... \Var{abc_def} ... $\Var{abc_def}$ ...
    
  3. If it is an algorithm close to math, with short variable names, use italic. Otherwise, if it's more like a program, you could consider something like a typewriter font (see above).

  4. If you can easily separate the parameters, visually, it's fine, otherwise insert as much space as needed to make it readable. Often there is not much space (e.g. when typesetting in two columns), so inserting space everywhere even when not needed may not be the best choice.

  5. People like math mode because it is easy to add sub- and superscripts and typeset mathematical expressions in 2D instead of linearly. If you don't use mathematical expressions, you probably don't need math mode.

  6. Given a particular pseudocode package, one could implement support for referencing blocks, but I'm not aware that it has already been done.

  7. Again, it is a matter of taste or community how to typeset constants like null. Personally, I don't like boldface as it visually sticks out too much. Consider using typewriter font. Or if you are so close to a programming language, consider to use this language as pseudo-language with highlighting.

  8. This looks like Java, so why not write it in pseudo-Java using lstlisting, minting etc.

    As a side note, it is unusual when presenting an algorithm to refer to particular implementations like HashMap. Instead, one tries to abstract away from implementation details and stick to tuples, lists and sets (hence the preference for math notation). When discussing things like complexity, you will then assume that these abstract data types with their operations are implemented with an optimal data structure, assuming e.g. hashed keys and constant time for accessing elements.

3
  • Thank you for taking the time to answer my question, I will take your suggestions in mind. However - as a general remark and not as a critic to your answer - let me say that I am a bit disappointed by the wide space for subjective choices that there seems to be when it comes to pseudocode. I am one of those person with little to none "aesthetic taste" when it comes to chose spacing, margins, fonts and so on and, even worse, I do not know how to improve a bad result. So, I was not hoping to find the best way (which may not exist), but at least a few consolidated rules to follow.
    – Sirion
    Feb 6 at 17:55
  • @Sirion Look at a few papers in your field and check how algorithms resembling yours are written there. If you want to present a truly abstract algorithm independent of any programming language, it is less a matter of aestetics but a real intellectual effort. But then you will end up with mathematical structures, and math mode. On the other hand, if you want to stay close to a program, just leaving out irrelevant syntax, then write it in this pseudo-language with syntax highlighting. Mimicking it with math mode probably yields poor results.
    – gernot
    Feb 6 at 18:37
  • @Sirion If you are unsure about the quality of your typeset algorithm, post part of it and ask for improvements. On the other hand, if it's a thesis ask your supervisor; if it's a paper, you will get peer reviews. If there are no complaints, then the quality apparently was good enough.
    – gernot
    Feb 6 at 18:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.