Part I Concepts
10.1 Presenting Non-Numerical Data
10.1.3 Presenting Data from Implementations
An implementation can be part of your method for various reasons, for example, if you rely on simulation data and need to implement the simulation model or the simulation tool yourself. In other cases you may implement a system in order to demonstrate that something can be done, or as part of testing a method for systems development. In all these cases, it is necessary to use good software development practice, part of which is to document the implementation well.
Since the implementation is part of your method for the project, you also have to show as much of the documentation as is needed in order to convince the reader that the implementation is correct. For example, you might have implemented an algorithm and performed some simulations where you compared it to another
Table 10.1 Different ways of structuring the presentation of collected data
No grouping Grouping Summary
Structure by company
Company A Company A Company A
• Q1 • Q1-Q5 • Summary of Q1-Qn
• Q2 • Q6-Q8 Company B
• Qn Company B • Summary of Q1-Qn
Company B • Q1-Q5
• Q1
• Q2
• Qn
Structure by question
Q1 Q1-Q5 Q1-Q5
• Company A
• Company B
• Company A
• Company B
• Summary of company A and B
Q2 Q9-Qn Q9-Qn
• Company A
• Company B
• Company A
• Company B
• Summary of company A and B Qn
• Company A
• Company B
algorithm. Maybe you have already described the algorithm very clearly in your report, but in order to convince the reader that your simulation data are meaningful, you must also demonstrate that the simulations were done with a correct implemen- tation of the algorithm. In other words, you must convince the reader that the differ- ences observed between the algorithms are not caused by errors in the code.
So, how do you present the implementation in a way which convinces the reader that it is correct? One thing to rule out immediately is to simply list the code, and expect the reader to verify that it is correct. Computer implementations often contain thousands of lines of code, and even a short implementation of a hundred lines or so is hopelessly difficult to verify by manual inspection.
Instead, you have to demonstrate to the reader that you have used good software development practice, and show the steps in the process of developing the imple- mentation. An example is to first show the algorithm in pseudo-code and explain relevant parts of the pseudo-code in writing. You can then show a graphical representation of the code, using, for example, flowcharts or some other graph for- mat, which is appropriate for the particular algorithm at hand. This graphical representation should also be discussed in the text so that the reader has a very clear understanding of it (and is convinced that you do too). Finally, you can present rel- evant parts of the code, i.e. those parts that contain the key features of the imple- mentation. This technique is particularly useful if you are using the implementation for the purpose of, for example, showing that a programming language or a model lacks (or contains) certain features. In that case, these code examples may be the main part of your data.
Figure 10.1 and 10.2 show brief examples of the description techniques outlined in the paragraph above. For further details about writing pseudo-code and using graphical representations of code you should consult introductory textbooks in com- puter science or software engineering. It is important to realise, however, that these techniques are not sufficient for all types of implementations in all types of projects.
You may implement a much larger software where it is necessary to use higher-level description techniques, or you may implement safety-critical software where it is necessary to demonstrate that you have used a formal verification procedure to check the programs for correctness. In short, you should use the type of description technique which suits your project and type of implementation best, and apply it in such a way that you demonstrate to the reader that you have done a good job.
Additional tips:
● Where to put code. Most of the code you write should be placed as an appendix to the report. No one is going to read large amounts of code, and it is therefore just distracting to see it in the middle of the text. However, as mentioned earlier, you can include short sections of code within the text to demonstrate how par- ticular implementation problems were solved, or to demonstrate the absence or presence of particular features. Code sections that are included in the text should be only a few lines long. If you are allowed to use supplementary media for your report, you can for example provide a CD-ROM containing the code, or make it available on a web site.
10.1 Presenting Non-Numerical Data 77
AHPA
Initializations Generations
One generation
Evolve solutions
Evolve fitness cases (t < maxgen)
*
Fig. 10.2 Graph representation of the example algorithm from Fig. 10.1, using the Jackson Structured Programming graph conventions
initialize( He) initialize( Hs) initialize( Pe) initialize( Ps) while (t < maxgen) do
until ( (h ∈He) and (h solves Pe艛 (PS) ) evaluate( He, Pe艛 Ps
reproduce( He) t = t + 1 end add h to Hs
until ( ( p ∈ Pe and ( p defeats He艛 Hs) ) evaluate( Pe, He艛 Hs)
reproduce( Pe) t = t + 1 end add p to Ps end
Fig. 10.1 Pseudo code representation of an example algorithm
● Commenting. All the rules of commenting code that apply in software engineering also apply to code written as part of a project. In other words, all code should be commented carefully and systematically. Any good textbook on software engineering will contain thorough guidelines on commenting. You should read those guidelines, and apply them meticulously.
● Other information. Depending on the purpose of the implementation, you may have to provide the reader with other information about the software. Examples include hardware and software requirements, user instructions etc.
If you have built a simulator you can also validate the implementation by using reference algorithms (i.e. baselines). By doing so you show that your implementa- tion behaves correctly with respect to already established algorithms and baselines.