#bib bibliography

The BibTeX code you get from the ACM Digital Library or IEEE Xplore or whatever is usually terrible. You need to fix it up manually:

• Remove all the useless fields like publisher and keywords. For inproceedings (conference) entries, keep only author, title, booktitle, and year.
• Edit the conference name (booktitle) to be less rambly. Remove stuff like Proceedings of the 32nd ACM SIGPLAN Conference on... and use something succinct like Programming Language Design and Implementation (PLDI). Include popular abbreviations in parentheses to help readers skim. When submitting to a venue with unjust page-limit rules that include references, consider using the abbreviation by itself to save space (and as a form of protest).
• Check for capitalisation in the title and surround it with curly braces. For example, use {PRIMES} is in {P} to make sure BibTeX doesn’t render it as Primes is in p.
• Be especially careful of publications coming from SIGPLAN Notices or SIGARCH Computer Architecture News—they are usually reprinted from a conference, such as PLDI or ISCA.

If you find something on arXiv, always look for a real publication first before resorting to an arXiv citation.

#capitals capitalisation

Use capital letters at the start of a sentence, for proper nouns and in acronyms. Don't be tempted to use them as the first letter to highlight specific words (use emphasis instead) or when you're going to make an acronym. Instead of:

This results in a Completely Automated Knowledge Extractor (CAKE)...

Write:

This results in a completely automated knowledge extractor (CAKE)...

#caption captions

Use captions to explain figures, tables, algorithms, etc., rather than limiting them to only a few short words. Having explanations in the captions (even if they run to several lines) keeps those explanations with the content and means the reader will better understand what you are showing them.

Captions should end in a full stop; sub-captions (e.g. for subfigures) shouldn't. Captions should appear below the content being described.

#citet citation as nouns

Citations are not nouns. For example, this is wrong:

• We build on the work of [32].

The right way is to either name the system or the authors:

• We build on Terra [32].
• We build on the work of Cookie Monster et al. [32].

The natbib package for LaTeX defines the \citet macro, which automatically adds the names of the authors and the citation. It provides several other useful macros for citations.

When writing in LaTeX, put a tilde (~) before the citation macro to avoid a line break before it. For example:

• We all love LaTeX~\cite{Lamport}.

#comma commas

Do not use the Oxford comma (also called the serial comma) unless necessary to avoid ambiguity. In other words, don't have a comma before the final and in a list: locks, transactions and atomics. Be aware that both including it or leaving it out can introduce ambiguity, so read your lists carefully.

Unsurprisingly, omitting this comma differs from the advice in the New Oxford Style Manual, but in my opinion it looks ugly.

#contraction contractions

Don’t use ’em in papers. They’re fine in blog posts ’n’ such.

#egie e.g. and i.e.

The abbreviation e.g. means exempli gratia (Latin), which translates to for example, and i.e. means id est (Latin), which translates to that is or in other words. Do not italicise them, and do not follow them with a comma. Instead, in LaTeX, use ~ after the dot to keep the spacing correct and keep them on the same line as the following word. Both need some kind of separating punctuation preceding them, such as a comma, an opening parenthesis, or an em dash. For example:

They forgot the most important thing in the world, i.e. breakfast. There would be no egg-based foods (e.g. omelettes or quiches) today.

Do not end a list that starts e.g. with etc.

#emdash em dash

In TeX, three hyphens (---) become an em dash (—).

You can use em dashes, sparingly, in place of parentheses or to evoke a conversational pause. See Eddie Kohler’s advice on how to use them. Do not put spaces around an em dash.

#emphasis emphasis

Use italics for emphasising text, not bold. Bold text stands out too much and gives the emphasis more weight than it deserves. It also often conflicts with the use of bold for section titles. Use emphasis sparingly.

In LaTeX, use \emph{} to emphasise text rather than using \textit{} since the former will correctly style emphasised words within an emphasised phrase and will use the correct style if the document class changes.

#endash en dash

In TeX, two hyphens (--) become an en dash (–).

Use an en dash, not a hyphen, in numeric ranges like 4–10.

Also use an en dash between words that are balanced with each other but not part of a compound word. Common examples include hardware–software, producer–consumer, and things named after multiple people, like Curry–Howard or Lucas–Kanade.

#figure figures

Float figures to the top of a page. This looks far better than having them placed between paragraphs within the text. When using LaTeX you may have to play with their positioning within the source so that they appear at the top of the page where they are mentioned.

#footnote footnotes

Footnotes at the end of the sentence go before the full stop when they refer to the last part of the sentence and afterwards when they refer to the entire sentence. In TeX:

Some intelligent point\footnote{By point we mean remark.}.
Some other intelligent point.\footnote{This was more intelligent than the previous one.}

#however however

However and similar words are not conjunctions, so foo, however bar is a comma splice. Try instead:

foo. However, bar

Or:

foo; however, bar

#hyphen hyphens

Use hyphens in compound modifier phrases when they help clarify which words go together. Specifically, hyphenate compound modifiers that come before the noun they modify, except when they consist of an adverb ending in -ly. Do not hyphenate compound modifiers that come after the noun they modify unless you have a really good reason to.

For example, you need a hyphen in language-based security, off-chip DRAM, and real-time deadline but not in this accelerator is fixed function. On the other hand, fully connected layer does not need a hyphen, even though the modified noun layer comes last, because the -ly suffix in fully makes it easy to see how to parse the phrase.

Some phrases can act either as modifiers that need hyphens or as nouns that do not. The phrase state of the art is a common bugaboo. A reference to something in the state of the art does not need hyphens, but a state-of-the-art accelerator does.

Usually a modifier affects the whole of the phrase that follows, up to the final noun. So a standard library function refers to a library function that comes as standard, whereas a function from the standard library is a standard-library function. However, a hyphen should still be used in situations where it is obvious that the modifier only affects the next word because the usual meaning doesn't make much sense, such as a data-cache port.

#inline inline maths & code

You often want to put maths, code or other notation in the flow of prose. Do it like this:

Introductory sentence, ending with a colon:
%
\[ e = m \times c^2 \]
%
More explanation here.

The text leading up to the notation should give enough context so that the reader knows why they are about to see an equation. It should call out the key insight they should look for while trying to understand the maths or listing. The text afterwards should provide justification and explain details that make sense after seeing the notation.

Above and below the maths or listing, use an empty TeX comment line (%) to avoid starting a new paragraph whilst still making the TeX look readable.

For maths, be sure to use display-mode maths macros like \[ x \] or align*. Use align* (instead of several \[ \] equations in a row) when you have multiple lines:

\begin{align*}
S &= \frac{T_s}{T_p} \\
  &= \frac{1}{(1 - p) + \frac{p}{s}}
\end{align*}

#list lists

If you have to list items that are only a sentence or two, consider inlining them into a paragraph, following these rules, where it reads well. (1) There’s no need for fancy marker words like firstly and secondly. (2) Instead, use numerals in parentheses at the beginning of each item. In LaTeX, this can be easily achieved using the inline option to the enumitem package.

#maths maths

In LaTeX maths:

• Don't use * for multiplication. Use \cdot, \times, or nothing at all.
• For variable names that are words, use $\text{count}$. A plain $count$ looks like you're multiplying five single-letter variables together.

#passive passive voice

Avoid the passive voice as much as reasonable. Instead of saying the data is converted, for example, your writing will be clearer if it is more specific about who or what does the conversion: the system, the algorithm, the user, the server, the authors, etc.

An imperfect way to tell whether a sentence is in the passive voice is to try adding …by space aliens to the end. If that works, you probably want to add a subject for your verb. (Credit to Melissa O’Neill for this trick.)

Sometimes, rewriting a sentence to avoid the passive voice makes it worse. Give it an earnest try, but give up if the alternative seems bad.

#quote quotes

Full stops and commas at the ends of quotations go inside the quotation marks if the whole sentence is the quote, but outside if part of the sentence isn't a quote. For example:

My advisor texted me that I had 'fixed the last bug', but I replied that 'bugs are forever'. 'Yes,' she said, 'I've just found another!'

In TeX, remember to use ` for opening and ' for closing single quotation marks, or two of each for double. TeX will typeset 'this' with opening quotation marks on both sides, which is incorrect. Note that single quotation marks are preferred in British English, with double quotation marks used for a quote within quotes.

#ref references

To reference a section, use section~\ref{...}. Only capitalise section if it starts a sentence and use a tilde to make a nonbreaking space. (And the same for tables and figures.) Always use section, even when it’s a subsection or subsubsection.

When explaining figures or tables that show results, refer to them early in the paragraph, usually in the first sentence, and then explain the contents in more detail. For example:

Figure 9 shows the execution time for each benchmark relative to an unmodified execution. The geometric mean slowdown is 8%. The worst slowdown is streamcluster, which is 31% slower with debugging enabled.

It’s usually best to put the figure or table reference right at the beginning of the sentence and to follow it with an active verb. For example, prefer Figure N shows X to X can be found in figure N or As shown in figure N, X.

In LaTeX, consider using the cleveref package to help with this formatting and to deal with lists of multiple labels automatically.

#runtime runtime, run-time, run time

Use run time as a noun for the time when execution happens, as in the error arises at run time. Use run-time as an adjective phrase before the noun, as in the system’s run-time behaviour. Use runtime as the noun that is shorthand for runtime system, as in we designed a compiler and runtime. (Credit to James Wilcox’s recollection of Mike Ernst.)

Use the same rules for compile time and compile-time (but compiletime is not a thing).

#sectitle section titles

In general, prefer sentence case for section titles (and, indeed, the title of the work). For 'run-in' titles like LaTeX's \paragraph, use sentence case and end the title with a full stop.

#simplify simpler phrases

Writing in “academic mode” can tempt you to use phrases that are more complicated than they need to be. Try to keep things simple, even if it means sounding informal. Here are some find/replace patterns for simplifying language:

• which means that → so
• gives X the ability to → lets X
• allows X to → lets X
• is different → differs
• is built on → builds on
• it is observed that X → just X or, if necessary, we observe that X
• in order to → to
• so as to → to
• as can be seen in the figure, X → the figure shows that X or just X
• has the potential to → could
• a sufficient amount of → enough
• utilise → use
• make use of → use
• note that X → X
• it is worth noting that X → X

#subfig subfigures

Use the subcaption package to lay out subfigures in TeX. Use something like this:

\begin{figure}
    \centering
    \begin{subfigure}[b]{0.5\linewidth}
        \centering
        Figure here.
        \caption{First caption.}
        \label{fig:thing1}
    \end{subfigure}
    \begin{subfigure}[b]{0.5\linewidth}
        \centering
        Another figure here.
        \caption{Second caption.}
        \label{fig:thing2}
    \end{subfigure}
    \caption{Caption for both.}
    \label{fig:both}
\end{figure}

Using 0.5\linewidth for the size of the subfigures makes them divide the horizontal space equally.

#table tables

In TeX, use booktabs and its \toprule, \midrule, and \bottomrule lines instead of \hline. Do not put horizontal lines between every row (but between the header row and the rest of the rows is fine). Do not use vertical lines. Right-align columns that contain numbers.

#they personal pronouns

To refer to a notional person like the programmer, use the singular they.

#this this as a subject

It can be tempting to chain together two sentences by starting the second one with this as a noun. For example:

Because the oven was broken, we microwaved the hot pocket. This resulted in a quicker but soggier treat.

This pattern can make the second sentence harder to read because the referent can be ambiguous (at first glance, this might be the hot pocket, the oven, or the microwave). Insert a clarifying noun, such as this technique in the sentence above.

#times times

Use a × symbol, not the letter x, when writing about dimensions (“a 4×2 grid”) or factors (“a speedup of 2.3× over the baseline”). In TeX, you can use $\times$ to get the symbol.

#tradeoff trade-off

Use trade-off, not tradeoff. (Both are common, but we had to pick one and the former seems to be more popular.)

#transpiler transpiler

Avoid transpiler. Just use compiler instead. (See Lindsey Kuper’s investigation into the varied, fuzzy meaning of the former.)