Why the way you present code matters
In computational theses the code often embodies the method, so how you present it affects how well an examiner can judge your work. Examiners need to understand what your algorithm does, why it is designed that way and whether the results it produced can be trusted. They rarely need to read every line. A thesis that presents a tool or technique should make its result and its validation clear, as good software engineering research papers do (Shaw, 2003).
Presentation is also part of reproducibility. Computational results are increasingly expected to come with the code and data that produced them, so that others can check and build on them (Peng, 2011). Experience shows why this matters: when researchers tried to obtain and build the code behind hundreds of computer systems papers, much of it could not be obtained or built (Collberg & Proebsting, 2016), and in a recent sample of 100 replication packages from a leading software engineering conference only 40 ran fully, and 14 of those reproduced the reported results (Muttakin et al., 2026). Your thesis can do better.
Three forms of code in a thesis
| Form | Use it for | Where it goes | Typical tools |
|---|---|---|---|
| Pseudocode (algorithm) | Showing the logic of a new or adapted algorithm, independent of language | Main text, numbered as Algorithm 1, 2 ... | LaTeX algorithm environments (algorithm2e, algpseudocode) |
| Short source listing | Showing an implementation detail that matters to the argument, an API use or a configuration | Main text (short) or appendix, numbered as Listing 1, 2 ... | LaTeX listings or minted; Word with a monospaced style |
| Full code base | Allowing readers and examiners to run, inspect and reuse the work | Archived repository, cited in the thesis | Version control plus an archive that issues a persistent identifier |
As a rule, describe your method in prose and figures, present the key algorithms as pseudocode, show a listing only when the exact code is the point, and put everything else in an archived repository. Check your university's regulations on appendices and supplementary files: some limit appendix length or allow electronic supplements to be deposited with the thesis.
Think also about where code appears in the structure of the thesis. The methodology or design chapter usually presents the algorithms and the architecture of the implementation; the evaluation or results chapter reports what the code produced, with the experimental set-up; and an appendix or data availability statement tells the reader where the archived code and data can be found. Keeping these roles separate stops implementation detail from crowding out the argument.
Writing pseudocode
Good pseudocode is precise but not tied to a programming language. State the inputs and outputs, number the lines, use standard control structures (for, while, if, return), use mathematical notation where it is clearer than code, and omit details such as input parsing or logging that do not affect the logic. Give each algorithm a number and a caption, and refer to it in the text before it appears.
| Line | Algorithm 1: Sliding-window z-score anomaly detection (illustrative) |
|---|---|
| 1 | Input: series x1, ..., xn; window length w; threshold k |
| 2 | Output: set A of indices flagged as anomalous |
| 3 | A ← empty set |
| 4 | for t ← w + 1 to n do |
| 5 | μ ← mean of xt−w, ..., xt−1 |
| 6 | σ ← standard deviation of xt−w, ..., xt−1 |
| 7 | if σ > 0 and |xt − μ| / σ > k then |
| 8 | add t to A |
| 9 | return A |
In the text, explain the design rather than the syntax: "Algorithm 1 flags a reading when it lies more than k standard deviations from the mean of the preceding w readings (lines 5 to 7). The guard on line 7 avoids division by zero in constant segments. As written, each step recomputes the window statistics, giving O(nw) time; maintaining running sums reduces this to O(n)." Referring to line numbers lets the examiner follow the argument without reading the whole algorithm.
In LaTeX, the algorithm2e package, or the algorithmicx bundle with its algpseudocode style inside an algorithm float, produces numbered, captioned algorithms with line numbers; in a word processor, a numbered table or text box with a monospaced or clearly indented style serves the same purpose. For thesis set-up in LaTeX more generally, see Writing a thesis in LaTeX.
Formatting source listings
- Keep it short. Show the 10 to 30 lines that matter, not whole files; mark omissions with a comment.
- Use a monospaced font set once in your template, with consistent indentation.
- Number lines so that the text can refer to them.
- Caption and label each listing ("Listing 3: Training loop with early stopping") and cross-reference it.
- Highlight sparingly. Syntax highlighting helps on screen; check that it remains legible in greyscale print.
- Follow the language's style conventions, such as PEP 8 for Python, so that the code reads as professional.
- Comment for the reader: explain why a step is there, not what each line does.
- Avoid screenshots of code; they cannot be searched, copied or read by screen readers.
In LaTeX, the listings package typesets code natively, with options for language, line numbers, caption and label, for example \begin{lstlisting}[language=Python, caption={Training loop}, label=lst:train]. The minted package gives richer highlighting but relies on an external highlighter and may need extra compiler settings, which can complicate building the thesis on another machine. Whichever you use, include listings from the source files rather than pasting copies, so that the thesis shows the code that actually ran.
Archiving and citing the full code
The full code base should be available in a form that will not change. Use version control throughout the project, and when the thesis is submitted, tag the exact version used and deposit it in an archive that issues a persistent identifier such as a DOI; repository platforms can be linked to archives that do this automatically. Then cite that version in the thesis. The software citation principles set out why and how: software is a legitimate research product, citations should credit its authors, identify it uniquely and persistently, give access to it, and specify the exact version used (Smith et al., 2016).
- A README explaining what the code does, how to install it and how to reproduce each main result.
- A record of the environment: language and library versions, ideally in a lock file or container definition.
- Scripts that regenerate every table and figure from raw or processed data, without manual steps (Sandve et al., 2013).
- Fixed random seeds, and a note of hardware where results depend on it.
- A licence, so that others know whether they may reuse the code.
- Data, or instructions for obtaining it, described so that it is findable and reusable (Wilkinson et al., 2016).
For machine learning work, also report data splits, hyperparameter searches and computing resources, as reproducibility checklists in the field require (Pineau et al., 2021), and check for data leakage between training and test sets, which can make results irreproducible even when code is shared (Kapoor & Narayanan, 2023). Where you report run times or memory use, describe how they were measured and on what hardware, because naive timing can be misleading (Beyer et al., 2019). For a fuller treatment of reproducible programming practice, see Programming for AI research in a PhD.
Acknowledging other people's code and tools
Most research code builds on libraries, frameworks and examples written by others. Cite the main software packages your results depend on, with version numbers, in the same way you cite papers (Smith et al., 2016); many projects state how they wish to be cited in their documentation or in a citation file in the repository. If you adapted code from a tutorial, a forum answer or another researcher's repository, say so in a comment in the code and in the thesis, and check that its licence allows reuse.
The same transparency applies to code produced with the help of generative AI tools. Follow your university's policy on declaring such use, keep a note of where it was used, and make sure you understand, have tested and can explain every line that appears in your thesis or affects your results. In the viva you may be asked why an algorithm was designed in a particular way; being able to answer from your own reasoning is part of showing that the work is yours.
Common mistakes
- Appendices of hundreds of pages of source code that no examiner will read.
- Listings with no caption, number or reference in the text.
- Pseudocode that is really code in one language, with library calls and syntax details.
- Narrating code line by line instead of explaining the design and its rationale.
- Screenshots of code or of an editor window.
- Linking to a repository that later changes, without archiving and citing the version used.
- Results in the thesis that cannot be regenerated from the archived code and data.
- Failing to cite the libraries, tools and other people's code the work depends on.
For presenting the outputs of your code, see How to present PhD data in tables and figures and How to write the results chapter; for citing data and code in reference lists, see How to reference an econometrics PhD thesis. Annotated computing examples are in sample work.
Key takeaways
- Use pseudocode for algorithms, short listings for implementation details that matter, and an archive for the full code.
- Number, caption and cross-reference every algorithm and listing, and explain design choices in prose.
- Archive the exact version of your code with a persistent identifier and cite it (Smith et al., 2016).
- Make results regenerable by scripts, with recorded environments and seeds (Sandve et al., 2013; Peng, 2011).
- Shared code often fails to run or reproduce results, so test your archive before submission (Collberg & Proebsting, 2016; Muttakin et al., 2026).
