Amount of pseudo code in the thesis body

Question

I'm writing my undergraduate thesis (~25 pages) on a computer program I've developed. Naturally, I'm expected to explain what the program does and how it is implemented. However, the algorithm is quite complex and I simply cannot afford to include a full description.

What do you think, should I:

• Lay out the general contours in writing and leave out the semi-obvious implementation details. The amount of detail should be enough to reproduce my work, but it would look rather vague and hard to read.
• Include main pieces of the algorithm (written in pseudo code) in the body and use comments to explain what is going on. I'm leaning towards this one, as the work looks more readable this way. However, cumulatively these bits and chunks amount to 3.5 full pages of code.
• Put pseudo code in the appendix. But in this case the major part of the explanation would be done in the appendix and the body would look kind of empty.

Answer 1

Use block diagrams

Block diagrams are effective for conveying the functionality of the program and abstracting away complex and/or banal code. For my dissertation (novel implementation of controller for exhaust gas recirculation), I used block diagrams to cover the overall functionality of my code and subsequent sections to explain non-trivial implementations.

If you are not pressed for a page/word count and feel like the only way for the program to be understood is a full explanation: fully explain it. For the sake of the sanity of your reader, your second bullet point seems most prudent: Explain rather than disclose simple and obvious code in the main body and disclose it in the appendix. Novel code implementations should be disclosed and explained in the main body of the report.

For my undergraduate dissertation I opted for this method. For example, my code modelled the control system and a DC motor. The DC motor model was trivial and unoriginal (the governing differential equations can be derived or looked up easily) and so a simple mathematical explanation of the torque and armature current equations in the main body was sufficient.

Answer 2

There are couple of things need to be mentioned here. The following holds from your undergraduate thesis now, until the end of your PhD thesis:

Clear Introduction: I want to see a solid introduction in your thesis. Here I want to know the problem, aim and solution in a very clear format. Do not dump any main stream code (e.g., Java, C++, etc.) here, I want to see if you can explain the big picture clearly. You could however use under 10 line of pseudo code for each section (problem, aim, solution) if necessary. Do not go overboard and way too much into details. Obviously here, you could use screen shots of your work or figures that demonstrate the overall scenario.

Your Work: In the chapter(s) that explain your work, you still use pseudo code but you bring the depth of your work here. If the reader can't get it, they can go back to your introduction. Do not mess around in this one. Still solid and clear but it should show you know your work. You can use algorithm, work flows, user interaction flows, and other related topics here. If you are good with word processor or Latex, and know how to print you can add A3 pages here and there if your figures becomes huge.

Appendix: Moreover, for having a solid thesis, you can use Appendices section to introduce your code in more details. For example you can just use the main classes, objects or functions and explain each individual ones. Do not add any boiler plate code here.

Related Repository Link: It is very easy to ask the university to grant you an access to the university student repository so you can add all your code over there and add the link to your thesis, so if the reader really wants to go through your code they can. You should also put your code within a CD and submit it with your thesis to overcome any doubt the reader might have about your code.

Answer 3

Use examples

Nothing is wrong with pseudo-code, but it shouldn't be the only tool to communicate what's going on. The brain of many readers, including myself, it wired to understand complex concepts (like algorithms) from concrete examples. Ideally, you should have a running example and show the input, output, and the result of all intermediate steps using this example. Sometimes there may be edge cases where a single running example is not enough. In these cases, it is still better to introduce additional examples than to avoid an illustration altogether.