Proper way to format computer code included in a thesis/dissertation

Question

I intend to include my computational model code(s) in its entirety as an appendix in my dissertation. I've gone through my university's formatting guidelines and haven't seen anything on the proper way to format the code in terms of size of font, text-wrapping, spacing, and so forth. What's the best way to do this?

When I read code, while I'd want it to be a typical font size (12 pt), I'd also want the text-wrapping to be minimal, but given the traditional margin requirements, it can be pretty tough to accomplish this. Having code trail off one line and onto the next is generally distracting.

Also, although comments in code are prevented from execution by using a character sequence like %or // or (* many compilers color-code this text to make it more easily distinguishable from executable portions of the code. Is there any way to easily make comments distinguishable when putting the code into the text of your thesis/dissertation?

Answer 1

Monospaced with syntax coloring and an appropriate description, see e.g.

from Appendix B of arXiv:1407.2432.

Answer 2

There are a number of excellent LaTeX packages for typesetting code, made for just such occasions. The listings package is one good example, which includes standardized formatting for a number of languages.

It does not provide a "definitive" way to typeset code (there is no such, since there are a number of competing conventions) but its defaults provide a standard and well-recognized formatting that is entirely appropriate for academic publications. Furthermore, it can be customized to follow any unusual requirements of your institutions thesis format.

Answer 3

I would suggest a monospaced font, because that is the traditional method of displaying code. As a matter of putting all of your code into the appendix, I don't see why. Snippets of the relevant parts would be all you need. If you still feel the urge to include the full code, I would suggest referencing a link to the code through a Github repository instead of all of your code.

In addition, ask your advisor who the audience is. Do they have a background in programming? That would be the question to ask. If not, summarize the code, and walk the reader through the logical process of the code. Perhaps a flowchart would be useful.

Answer 4

If you aren't required to do it in a particular format, I'd recommend publishing the code online and using a nice LaTeX code formatting package for the parts you want to share in the print version. My personal favorite is minted . Very easy to use, beautiful formatting and coloring and no need to copy and paste anything, just use the \inputminted command.

Answer 5

I would argue that there are no real style guidelines, except maybe (the only one I've ever been given) not to drown your audience in lines of code, thus use excerpts and pseudo-code whenever possible.

However, to still put your code full-length on paper, you pretty much should have it readable on-screen already. You might have a little refactoring to do, if you expect people to actually read it.

• Fixed font size are traditional in source code, which is due according to Joel Spolsky to it being easier to edit (say click on a specific letter) and to distinguish typos (e.g. rn/m vs rn/m) than when using a variable spaced fonts
• A fixed width so you never scroll horizontally while your code is on screen. This, with a correct font size, will take care of line wrapping when on paper.
• Modular code, so people know where (in which file, for example) they are : similarly to opening the interesting file, you want readers to be able to skip the pages of configuration, I/O and whatnot, to find wherever the core of your code is.
• Be consistent, as you already noted, in all conventions: naming, indentation, comments...
• include syntax Highlighting (maybe even colouring ?)

Your main options (most popular on a subjective scale of googleability) to achieve the latter are

• in LaTeX, use a listing (with a language that it understands, hopefully). You can even input code from a file directly \includecode[asm]{sched.s}
• in LaTeX, use the minted package, an alternative whose code highlighting is done with Pygments
• in MS Word, insert code in an embedded document as an "openDocument Text" object, copying your code from your usual IDE
• in any WYSIWYG on Windows, use the NppExport plugin of Notepad++ to export your code, and then copy it into your document as RTF or HTML.
• With any python interpreter, use Pygments, e.g. :
  pygmentize -f html main.c > main.c.html

---

The only guidelines I could find in the wild were on this random project report page, of rather small scale (4-6 pages), and they are rather succinct :

Format: Use [...] 11 point times font for the main text, and use 10 point courier font for computer code. [...]

Yes, your code should be in the appendix, monospaced, single column. You do not have to turn in all code used in your experiment; use your best judgement. You may want to include only relevent sections of code. For example, you should not include code that someone else wrote, unless you made major modifications. If your code is 100 pages, you should not print all of it. If your code is 6 pages, then you should print all of it.

Answer 6

The standard is to use 10 point courier font for computer code, monospaced, single column.

You do not have to turn in all code used in your experiment; use your best judgement. You may want to include only relevant sections of code.

EDIT Usage of Courier is of my personal choice from the list of standard 10pt fonts usable for codes.

Answer 7

the best way to display the salient code of the key points of your algorithm is to write good code.

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” -Martin Fowler, Refactoring: Improving the Design of Existing Code

the code itself should be readable with meaningful choice for variable names, sufficiently divided into meaningful functions or subroutines, and with a minimum of arguments passed around. this means writing decent object-oriented or structured code and making objects or structures and using them.

i would split the code up into modules with a good comment on the top of the file describing what the callable functions do and who calls them.