7

I'm writing some documents with embedded code listings. I reference such listings many times using something to the effect of, "...we provide an example as follows", with the block of code shown below as expected. What I'm unsure of, though, is the punctuation immediately after the word "follows". Should it be a period, a colon, or neither?

Example 1:

Below is an example of a tail-recursive factorial program:

versus

Below is an example of a tail-recursive factorial program.

Example 2:

We provide an example of XYZ as follows:

versus

We provide an example of XYZ as follows.

4
  • 1
    Possibly one thing you may not notice from EDL's answer (which I have given a +1) is not to use "below" but to always use "follows" or "following."
    – Boba Fit
    Jun 11, 2023 at 16:20
  • @BobaFit Thanks for the suggestion! Is that because "below" just sounds awkward in comparison to "follows" or "following"? Jun 11, 2023 at 17:08
  • 4
    No. When you turn the page, it may not be "below" but "over there." But it always "follows." Similarly, don't say "above" but "previously."
    – Boba Fit
    Jun 11, 2023 at 17:12
  • @BobaFit Good point! Jun 11, 2023 at 17:16

4 Answers 4

10

Assuming this is not for a non-fiction publication, but something more informal like a school report, or product documentation in some sort of HOWTO then using the colon to signify a transition from talking about the code to few dozen lines of code is a very standard approach.

This screenshot is from a standard book on C++ programming.

C++ example

If this is for a non-fiction publication, then examine the submission guidelines for the publisher. They may want code to be separated from text since code is often representing in a different font type and size. This lets the editors read the writing without needing to be experts on code as well. Plus, a publisher needs to determine that any code shared in their books isn't copyrighted or plagiarized from someone else or needs proper declarations to comply with Open Source guide lines.

1
  • 1
    For the purposes of integrated context, this is for a textbook that I'm writing. I have gone back and forth between using and not using colons, and this answer clears that up. Thanks! Jun 11, 2023 at 3:03
10

I try to avoid both "as follows" and "below". (Some book publishers love them because they feel they are more formal, but when I have a choice, I avoid them.)

Instead, I use "this" or refer back to things by name if they've already been discussed. Here are some examples from a book I co-wrote in recent years:

There are three places where you can initialize member data. The first place we’ll take a look at is the constructor function body. Consider this class:

(a longish piece of C++ declaring a class follows)

A page or so later, after talking about possible problems with it:

Let us change the constructor appropriately:

(just the revised constructor code follows)

Still later, after some musing about possible changes to such a class over time:

Consider what might happen to the piano class were three maintainers let loose upon it:

And so on. This is a more conversational style but I feel it works. Note that in all three cases, we used a colon -- I think that is the more common punctuation there.

1
  • 1
    Yes, this - there's no need to keep putting a (monotonous) "as follows"; the colon tells you all you need to know! In addition to the examples in this answer, another would be when demonstrating a particular construct or technique, where you could say "We can implement this solution using the Widgetiser pattern:"
    – psmears
    Jun 13, 2023 at 13:09
4

Based on some classic examples, I say avoid forcing a colon, and avoiding using wording that serves only to introduce a code block.

Numerical Recipes in C is a classic text, nicely typeset. The authors don't use colons before inline examples, and minimise the use of introductory phrasing, instead using structures that read more naturally. The treat equations the same way as code except that equations are numbered.

image from Numerical Recipes

Another classic is Kernighan and Ritchie, also a clear and well-written book. They use the following style

For example, the following function reads ... from an arbitrary place in a file. It returns the number read, or -1on error.

#include "syscalls.h"

/* get: read n bytes from position pos */

etc.

They use a construction involving terms like "follows" at times, but again the flow is often more natural without. If you're discussing an example, then an example appears, it's usually clear what that example is doing.

As with equations, single lines of code can appear in mid sentence. Then no punctuation is used, unless it would appear at that point in the sentence anyway.

Other books of similar vintage do use a colon for every inline example. It often looks wrong, especially for examples within a sentence.

Note that a lot of more modern texts put all listings greater than a handful of lines, or even all that don't sit within a sentence, in a floating environment that can then be referred to by number as a figure would be. Press, et al. in Numerical Recipes have to refer to the section in which an example sits, instead. Modern typesetting does tend to break things out into boxes more often than older work. (My terminology here is that of a LaTeX user)

2
  • 1
    I agree that using "as follows" or "the following" breaks the natural flow of dialogue. The solution I have for large-ish blocks of code is just a lstlisting environment wrapped in a tcolorbox, which looks well enough. It's mostly just a matter of finding the right verbiage to introduce the code :-) Jun 13, 2023 at 0:54
  • 1
    @TheProgrammer an inline tcolorbox, rather than a floating one, by the sound of things. I rather like the style "The function myfunc does some stuff to some variables and returns the result.\\ \begin{tcolorbox{\\ \begin{lstlisting{\\ \def myfunc():..." as done well it makes it clear that you're describing the code that's coming up, while still reading naturally. For single line snippets, something like "Recalling that $\theta$ must be given in radians, \\ \texttt{x=math.tan(\theta) \\ will give us the required result" again keeps text flowing
    – Chris H
    Jun 13, 2023 at 8:47
-1

In writing as such, there are no clear rules for what you’re describing. If there were, you should have found them with most search engines before coming here, and anyone Posting a generally-accepted Answer would be able to cite them. With very little exception, the same applies to most specialised writing.

Is this actually about writing, or coding, or presentation in general? If it’s about coding or presentation in general, how does it belong best in SE Writing, please?

In writing, the basic choices are to ask the senior editors of whichever organisation you’re working with, or devise your own rules.

In ordinary English - which this clearly is not - ‘…an example as follows’ can’t use a period. That very period would mean the expression was complete, the example was separate and in the sense of logic quite literally no, the example didn’t follow. Please note that’s the logic of the content, not of the trivial flow of the text.

To the extent this might be treated as ordinary English, the sole function of the colon is precisely as you describe, to separate following detail from an initial introduction while perhaps breaching several rules of punctuation, grammar or syntax.

The visual presentation of your exposition suggests that by form as well as content, the closest this could come to ordinary English would be as a list, which would automatically put it beyond the reach of ordinary rules.

If the ‘neither’ choice here means ‘nothing’, that’s fine; lists, like headlines, follow their own rules… or rather, their authors’ rules but either way, not the rules of ordinary English.

If the choice includes anything else, lists and headlines certainly and ordinary English increasingly allow an ellipsis ‘…’ there…

Quite separately, the idea that it’s better not to use ‘below’ but always ‘as follows’ or ‘following’; not ‘above’ but ‘previously’ would be purely personal choices but for the given explanation, which deserves consideration.

Whether ’When you turn the page, it may not be "below" but "over there" ’ is true depends entirely on the size of the page; not the intentions of the writer or editor, the publisher or printer or even the reader.

Most obviously, if a text moves from hard- to paper-back, the page size will prolly change and most likely, shrink but that’s a very modern option. Does any writer think the text should be changed to accommodate something so trivial?

For hundreds of years before paper-backs hit the market, no meaningful part of the publishing world saw ‘below’ or ‘following’ nor ‘above’ or ‘previously’ as referring to anything but the way text might appear in a single, continuous scroll - which is where the use of ‘above’ and ‘below’ arose.

5
  • 2
    "Is this actually about writing, or coding, or presentation in general?" This is explained quite clearly in the first sentence of the question: "I'm writing some documents with embedded code listings." Questions about formatting a document are perfectly on-topic here.
    – F1Krazy
    Jun 28, 2023 at 19:20
  • @F1Krazy I'm not going to argue about this, and I do point out both that your interpretation of the guidelines seems rather slack, and that it's interesting you chose that point to pick… Jun 28, 2023 at 19:41
  • I thought my explanation in the first sentence was clear enough, but to clarify, I'm trying to determine what is the best transition from a paragraph/sentence to a code listing. Jun 28, 2023 at 20:31
  • Yes and to clarify, that's the point… the idea of a transition from a paragraph/sentence to a code listing is a concept far too new for any rules of grammar, syntax or the like to have caught up, whether those were purely about printing on paper with no regard to the content, or publishing the content with no regard to the medium. Much of the trouble here is that the Question has at best very little to do with 'writing' but that's a problem for the Forum, not the language… More: Jul 9, 2023 at 22:39
  • Further… to put it more simply, in what way is this about English, rather than French or German, Greek or Latin, Punjabi or whatever they speak in Zambia? Who thinks this is part of 'English' is welcome to justify that… Would anyone like to try? Jul 9, 2023 at 22:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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