19

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?

18
  • 3
    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.
    – user479
    Jul 8, 2014 at 2:52
  • 1
    a monospaced font...is best to use for readability — [citation needed]!
    – JeffE
    Jul 8, 2014 at 7:45
  • 4
    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 8, 2014 at 10:07
  • 7
    @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 8, 2014 at 11:14
  • 2
    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 8, 2014 at 21:09

7 Answers 7

8

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

enter image description here

from Appendix B of arXiv:1407.2432.

2
  • 1
    How is this typeset? By means of a LaTeX package like listing?
    – enthu
    Feb 1, 2015 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. Feb 2, 2015 at 9:46
8
+25

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.

6

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.

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.

3

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.

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.

2
  • 7
    Do you have a source for this "standard"?
    – ff524
    Jul 15, 2014 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. Jul 15, 2014 at 17:29
1

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.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .