18

I am writing my master of science thesis and I am not sure whether I should add some of the code I have written: they are not proper programs, but more like input files to be fed to a commercial program (Nastran) very popular in my field.

My concerns are related to the fact that I am not making any discovery, just applying the things I have learned reading the manual. Still, I feel the code will make the effort I put into the thesis to also learn this language clearer.

5
  • 7
    I would propose that something like data input would be suitable for an appendix in the computer science field.
    – Compass
    Jan 28, 2015 at 16:06
  • 9
    When? Always. Including the input files. Everything.
    – Gimelist
    Jan 28, 2015 at 20:19
  • 3
    Please include the code. CS papers tend to be unreadable without any code.
    – Navin
    Jan 29, 2015 at 12:28
  • If there is any piece of code that is really important for your process, it should be in a float and commented. If there is any new trick, a fluxogram describing the new process should be used. Full code should be put on Github or Bitbucket and referenced, no matter if it is "just preprocessing". Perhaps a Gist? (labnol.org/internet/github-gist-tutorial/28499) Jan 29, 2015 at 16:27
  • 3
    @Navin That's very dependent on the paper. For most of the CS papers I write, there simply is no code to include. For many of the CS papers other people write, there's so much code that including it would make the paper far too long. And who ever reads printouts of more than a few lines of code anyway? Apr 12, 2015 at 20:55

6 Answers 6

7

My take on this -- in a physics PhD -- was that code that had a bearing on the results should be included in the appendix. I read in the entire source of my data-processing routines (using the listings package in LaTeX) and included them.

But I skipped bits like 40 consecutive lines of assigning defaults to variables (0s for later incrementing) or writing a default config file:

Skipped lines

(check the line numbers in the example) This is easy to do in listings, as is setting monospaced fonts and code highlighting.

I'm not saying this is the right way of doing it, just a sensible way. I may not even have implemented this approach as well as I could have done.

Of course, this will depend on your field. In my case the code was an important processing step in the results of some tricky new experiments. No-one is realistically going to want to replicate my code, checking some aspects of it is another matter. And yes, I do have every intention of making it available as well -- but it would be of limited use given that my coding style could at best be described as "scientist, self taught in Python".

2
  • 4
    I don't think this is a good approach: I can't see what anyone would want to do with a partial printout of your code. A description of what the code is supposed to do and a URL from which it can be downloaded would both be much more useful. (Though I assume the main text of your thesis already contains the former.) Apr 12, 2015 at 21:01
  • @davidricherby, while that's a nice idea it presupposes the existence of a suitable (by which I mean permanent and academic) URL. That option didn't exist for me. The electronic library copy of the thesis may be identical to the paper copy so that's no good. In my case I could save significant amounts of boring code and still include the routines that actually went to work on the data, while the overall process was described in the body (using flowcharts and assuming little or no programming knowledge).
    – Chris H
    Apr 13, 2015 at 7:31
29

Making your code available along with your thesis can be very helpful to other researchers who are trying to reproduce your results. I'd encourage you to do this.

However, you should not simply insert a printout of your code into the text of the thesis, since that will make it difficult (practically impossible) for someone to use the code that they obtain from a printed copy of the thesis or even a .PDF of the thesis. Rather, you should put the code into some online repository (such as e.g. github) so that others can download the code from the web.

5
  • I was thinking to put all the codes in an appendix not to interrupt the results-flow in the main body of the thesis. So I will add there also the link to the download page right? And another thing, should I comment the code to explain what I did or just show it?
    – Rhei
    Jan 28, 2015 at 16:38
  • 11
    Even printing the code out in an appendix is a waste of paper- just link to where it can be downloaded. You should always comment your code. Jan 28, 2015 at 18:11
  • 6
    Moderately small amounts of code can be copy-and-pasted from the PDF, if the packages used for including it are well configured (which is not always trivial to achieve). For larger amounts, a nifty trick is embedding the source files in the pdf. Jan 28, 2015 at 20:20
  • 2
    While I agree that this is probably the most useable approach, it may be the case that thesis regulations require you to include the code - if it is to be considered part of the thesis - as a hardcopy on a DVD or some such. Should be easy to check that, though.
    – G. Bach
    Jan 29, 2015 at 0:44
  • 1
    I'd find it massively more useful to have an appendix pointing to a stable repository of code and a description of what the code does than to just have an appendix of code.
    – Fomite
    Apr 13, 2015 at 18:07
9

In computer science, I am very much used to (and encourage) theses that contain any noteworthy code snippets as floats. In fact, as theses provide virtually unlimited space, there is no need for the extreme brevity of papers and a Concept chapter that describes the rationale for design decisions in the developed concept is usually followed by an Implementation chapter that can describe the implemented version in depth, including (but not limited to) showing presentation-worthy excerpts of the source code.

In most cases, this does not mean that whole source code files should be printed. This is usually referring to a few lines of code, or single methods that implement a specific algorithm.

For input/output files, things are similar, and they may be even more important than code snippets, as they may explain the handling and actual output of a prototype developed as a part of the thesis.

Contrary to various other answers here, I advise against putting any source code in the appendix in the usual case. The appendix is for extensive information that may be needed for further reference, but which is too "boring" to integrate in its entirety in the main body of text. This implies that the information in the appendix should be optimized so it can be taken advantage of in a meaningful way. In other words, the appendix in a (printed) document may be good for human-readable questionnaires or sets of tables, but full source code files should always be delivered in digital form (and in universities I am familiar with, (at least CS) theses have to be handed in as printed documents that are accompanied by a CD). Source code snippets that go into the main body of text as floats serve the same purpose as figures, tables or formulas in the main body of text - they illustrate something which would be too cumbersome to describe in the text.

8

@Brian Borchers's answer is sound, and it sounds like it would apply best in your case.

However, if you used a particularly interesting or novel algorithm to generate your input files (that is, you had unusual insight into how best to solve your problem that might help others), then in addition to linking your code to an online repository, you could provide a pseudocode description of that algorithm in your main body or an appendix, depending on flow. (If you're not sure if your process is sufficiently interesting, ask your advisor.)

1

Adding code snippets in the text achives two goals: first, it shows the implementation details and, second, it documents the code. The two goals are of course closely related and complement each other. In order to be valuable, however, the code should be split into parts (called chunks) that come in logical order in the text rather than in the order they are executed by a computer. (Thus no full code listing in an appendix.) In this way the code becomes an integral part of the text. This is an old idea of Don Knuth, known as literate programming. There are programs such as noweb that automatically extract the code and the human readable text from one source file.

0

I think you must contact your supervisor for a proper answer for this question because he/she will be the person who is going to evaluate your thesis.

If your course is more into technical stuff you might have to add more code than for a theoretical MSc.

My personal advice is to contact your supervisor/lecturer/tutor and get their opinion.

You must log in to answer this question.

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