How should I designate a break in a sentence to display a code segment?

Question

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.

Answer 1

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.

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.

Answer 2

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.

Answer 3

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.

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)

Answer 4

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.