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?

Does your advisor or school have specific suggestions? If not, pseudo-code of the core algorithm is probably most appropriate for the audience (thesis examiners). You. may always upload real code to github and cite that as well as an example implementation. — , Jul 08 '14 at 02:52
@leonardo I checked the university guidelines and there was nothing on code formatting. Advisor/committee members have no suggestions on this. — iwantmyphd, Jul 08 '14 at 02:55
Then I opt for pseudo-code. It let's readers whom are unfamiliar with a particular (or any language) read and digest the algorithm. Also, I would focus on the core algorithm as things like error handling will be cumbersome and distracting. — , Jul 08 '14 at 03:00
a monospaced font...is best to use for readability — [citation needed]! — JeffE, Jul 08 '14 at 07:45
Are you sure you need to "... include my computational model code(s) in its entirety as an appendix". Consider that, it's not read by many it would be; a) a waste of your money for the extra pages, and b) wasteful of paper. Maybe you can isolate the interesting bits and pieces only? — posdef, Jul 08 '14 at 10:07
@JeffE For fixed-form codes, monospaced font is a practical necessity. I admit I sometimes write Matlab code in sans serif, but that's because it is free-form. Anything indentation-sensitive or with large, hard-coded numerical arrays is much easier in monospaced font. And in dead-tree format, when it's hard to count the column numbers, a non-monospaced font could cause ambiguity in indentation-sensitive code. Reference: the practical experience of my forebears. — Moriarty, Jul 08 '14 at 11:14
@JeffE If you click on the word "monospaced", it was linked to the SE question/answer where I found that info. — iwantmyphd, Jul 08 '14 at 13:55
I understand that typesetting code in a monospaced font is a common convention. I'm disputing your claim that that convention increases readability. @Moriarty: Consistent, readable indentation and array alignment does not require a monospaced font. — JeffE, Jul 08 '14 at 21:09
@JeffE I understand your point, and am willing to edit my post accordingly to add a citation, or remove the monospaced paragraph completely. However, my main question was not about the font per se, but the font-size and text-wrapping. Also, line indentation, font color or shading for comments, and the like. Given your background and expertise, I would be very interested in your thoughts on this, especially since I am not in CS at all and my understanding of coding convention, formatting and archiving. Thanks! — iwantmyphd, Jul 08 '14 at 21:34
@posdef I've been asked by my advisor and dept head to include the code in an appendix in its entirety (even support files), even though they themselves (nor the college or university) had no suggestions on proper formatting for it. — iwantmyphd, Jul 09 '14 at 14:29
@iwantmyphd i see... Well, I hope you find a satisfactory answer in that case, unfortunately I have no idea if there is a standard way to include that much code. :) — posdef, Jul 09 '14 at 14:43
Put it on Github or your personal site or whatever and include a link to it in the thesis. — Jonathan E. Landrum, Jul 09 '14 at 16:11
Might it be better to host it on a repository such as Github and provide a link to it in your thesis? That way, people reading the code would have many of the advantages of repositories (e.g. searching for files, syntax highlighting etc.) — Isaac Woods, Jul 09 '14 at 16:14
In the bounty text you refer to "inconsistent indentation" and "commenting convention." Indentation and commenting conventions should be covered by the style guide for whatever language your code is in, regardless of what font face or size you use. — ff524, Jan 28 '15 at 04:59
@ff524 And the style guides you refer to are exactly what I am looking for. One code is MatLab, another is C, a third is Mathematica and a fourth G-Code (for CNC machines). — iwantmyphd, Jan 28 '15 at 05:02
Those have nothing to do with thesis, though. See e.g. C style guides (pick your favorite), MATLAB style guide — ff524, Jan 28 '15 at 05:09

score 8 · Answer 1 · answered Jul 15 '14 at 15:24

8

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

enter image description here

from Appendix B of arXiv:1407.2432.

answered Jul 15 '14 at 15:24

Piotr Migdal

26,252
10
74
126

1

How is this typeset? By means of a LaTeX package like listing? – enthu Feb 01 '15 at 20:58
1

@EnthusiasticStudent You can lookup its source. I see knitrout environment, though I cannot spot a relevant package. So it seems that it is an export from knitr rather than hand-written LaTeX. – Piotr Migdal Feb 02 '15 at 09:46

score 8 · Answer 2 · answered Jan 28 '15 at 05:03

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.

score 6 · Answer 3 · answered Jul 09 '14 at 18:58

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.

score 4 · Answer 4 · answered Jul 14 '14 at 20:26

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.

score 3 · Answer 5 · edited Jun 10 '20 at 14:12

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.

Jerric Lyns John · Answer 6 · 2014-07-15T17:37:35.647

2

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.

edited Jul 15 '14 at 17:37

answered Jul 15 '14 at 14:20

Jerric Lyns John

159
4

7

Do you have a source for this "standard"? – ff524 Jul 15 '14 at 14:22
1

@ff524 Yes, I primarily use LaTeX Source Code Listing which is like the standard way of writing a Computer Science thesis, especially if you presumably have more code in it. Arial/Courier are the 10pt standards used by Carnegie for publishing thesis through PQ/UMI, my preference is to use Courier. – Jerric Lyns John Jul 15 '14 at 17:29

score 1 · Answer 7 · answered Jul 14 '14 at 21:08

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.

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

7 Answers7

Linked