How to include source code into your dissertation

Including source code in your dissertation requires balancing technical accuracy with academic readability. You should use LaTeX listings or Word’s built-in formatting to ensure consistent syntax highlighting and proper referencing. This approach allows examiners to review your logic without being distracted by poor presentation, ensuring the code serves as evidence for your methodology rather than cluttering the narrative.

Choosing the Right Tool

The method you choose depends heavily on the document preparation system your university mandates. Most computer science and engineering dissertations are written in LaTeX because it handles large blocks of code more elegantly than word processors. If you are using Overleaf or a local TeX distribution, the listings or minted packages are standard. These tools allow you to define styles for various programming languages, controlling font size, background colors, and line numbers automatically. For those using Microsoft Word, manual formatting is often insufficient for long scripts. Instead, utilize the built-in "Insert > Object" feature or copy-paste from an IDE like Visual Studio Code while preserving rich text formatting. However, be cautious; rich text can break when moving between sections. A safer alternative in Word is to use a monospaced font like Consolas or Courier New, indented with a hanging indent style. This creates a visual distinction from the main body text without requiring complex plugin installations.

Structuring Your Code Listings

Academic writing demands that every piece of evidence be referenced. When you include a block of code, it must have a caption and a reference number, just like a figure or table. In LaTeX, wrapping your code in a listing environment allows you to use \caption{} and \label{}. This ensures that cross-references in your text, such as "as shown in Listing 3.1," resolve correctly during compilation. In Word, treat code blocks as figures. Go to the References tab and select "Insert Caption." Choose "Figure" as the label, but change the text to describe the code snippet. This integrates the code into your table of figures, making navigation easier for readers who want to jump directly to specific implementations. Ensure that the caption explains what the code does, not just its filename. For example, instead of "Listing: main.py," write "Listing: The main entry point handling user authentication."

Selecting Relevant Snippets

A common mistake students make is pasting entire files into their dissertation. Examiners rarely read every line of code. Instead, include only the critical algorithms, unique functions, or complex data structures that demonstrate your contribution. If a function is standard boilerplate, refer to the appendix or provide a link to a public repository if allowed by your institution. Break down large files into logical chunks. If you have a 500-line script, extract the core logic into the main body and move the supporting utilities to an appendix. Use ellipses (...) within the code block to indicate omitted lines, but ensure the surrounding context remains clear. This technique keeps the reader focused on the novel aspects of your work. Remember that clarity trumps completeness; the goal is to prove your method works, not to archive your entire project history.

Formatting for Readability

Readability is paramount. Code in a dissertation is often printed in black and white, so relying solely on color coding for syntax highlighting is risky. Use line numbers extensively; they help examiners locate specific parts of the code when discussing errors or optimizations. Keep the font size small enough to fit the block on one page but large enough to be legible. A 9pt or 10pt monospaced font is typically appropriate. Avoid horizontal scrolling. If a line of code is too long, wrap it manually at a logical breakpoint, such as after a comma or operator. In LaTeX, the listings package has a breaklines=true option that handles this automatically. In Word, ensure your paragraph settings do not force single-line breaks that push code onto new pages awkwardly. Consistent indentation is also crucial; maintain four-space or two-space indentation throughout all snippets to preserve the structure of nested loops and conditionals.

Referencing External Repositories

Modern dissertations often accompany a GitHub or GitLab repository. You should explicitly mention this in your introduction or methodology chapter. Provide a persistent URL, such as a DOI or a tagged release link, to ensure reproducibility. Do not rely on dynamic links that may change over time. When referring to the repository, clarify which version corresponds to the dissertation. If you update the code after submission, the examiner might not find the exact same implementation. Tagging your repository with the submission date or a specific version number mitigates this risk. This practice aligns with open science principles and adds credibility to your work, showing that your results are verifiable.

Common Pitfalls to Avoid

One frequent error is failing to compile the code before inclusion. Always verify that the snippets you paste actually run. Typos in included code can undermine your authority, suggesting carelessness in your research process. Additionally, avoid including proprietary or sensitive information. If your code contains API keys, passwords, or personal data, remove them before publication. Use placeholder variables like YOUR_API_KEY and explain how they were configured in your development environment. Another pitfall is inconsistent naming conventions. Ensure that variable names in your code match those described in your text. If you discuss "the learning rate parameter" in prose, the code should ideally use learning_rate or similar, rather than an obscure abbreviation like lr. This consistency reduces cognitive load for the reader, allowing them to connect your theoretical explanation with the practical implementation seamlessly.

Frequently Asked Questions

Can I include my entire source code file?

No, you should never include entire files unless they are extremely short. Examiners expect concise, relevant snippets that demonstrate your specific contributions. Long files distract from your analysis and waste valuable page space.

How do I handle code that exceeds one page?

In LaTeX, enable line breaking options to allow continuous flow across pages. In Word, split the code into multiple logical sections, each with its own caption. Never let a code block split awkwardly between paragraphs without context.

Is it necessary to highlight syntax colors?

Syntax highlighting aids readability but is not strictly mandatory if printed in black and white. Rely on line numbers and clear variable names to compensate for the lack of color differentiation in print formats.

Should I put all code in an appendix?

Critical code that supports your main arguments belongs in the body. Boilerplate, utility functions, or extensive configuration scripts are better suited for appendices. This keeps the main narrative focused on your unique methodology.

How do I reference code in my bibliography?

Treat code repositories similarly to software documentation. Include the author, title, version, URL, and access date. Use citation styles like APA or IEEE, which have specific guidelines for citing digital objects and software sources.