[html,12pt,a4]article C at_work.gif (Under Construction...) [1]#1 [1]``#1'' --- htmlonly [1]#1 [1]"#1" [1]#1 - htmlonly [2]#1#2 [2]#1#2 Software Engineering 1: Laboratory Report Guidelines Barry McMullin Last Modified: 28th March 1996 This document gives guidelines for the Laboratory Reports submitted for the course Software Engineering 1 http://www.eeng.dcu.ie/7Emcmullin/swe1/swe1root/swe1root.html. It also indicates the criteria which will be used in marking these reports. Note that these same criteria will be used in marking the reports submitted from the Laboratory Exams, which will determine the marks ultimately awarded for the course. If you have any queries or criticisms of these guidelines, please post them on the course mailing list at: SOFTENG1-95@mjmail.eeng.dcu.ie mailto:softeng1-95@mjmail.eeng.dcu.ie General The Software Engineering 1 Lab reports are submitted using email. This implies, of course, that they must be typed up. However, apart from this, the purpose and content of these reports is similar to reports prepared for any other Laboratory Course. Therefore, before reading these guidelines, make sure that you are familiar with the Undergraduate Laboratory Handbook http://www.eeng.dcu.ie/eenghome/labhbk/labhbk.html. That gives guidance for all Laboratory based exercises on your Undergraduate Programme, and outlines the general considerations applying to reporting all laboratory based work. These apply, as far as they are relevant, to the reports for the Software Engineering course also. The central principle of writing the reports for Software Engineering 1 is that they should explain where your time went during the lab session. If you successfully completed the assigned exercises, this can be relatively straightforwardcopies of the file(s) you created or modified, details of the tests you carried out and their results. The difficulty arises where you do not complete the assigned work. In that case, you have to explain, as clearly as you can, what the problems were: whether you simply did not understand the exercise, whether you ran into compiler messages that seemed unintelligible, whether you could not imagine how to test the program, or it worked on some tests and failed othersand so on. The point is that, if you spend three hours in the Lab, you must have done something: so report on what that something was, no matter how far removed it may seem from what was actually requested. Typing Up The reports must be prepared and submitted during the Lab session. It is recommended that you use PFE to prepare the report. Do not use any wordprocessing package such as Write, or MS-Word etc.The rationale for this is that such packages tend to embed additional information in the file, e.g. to specify the size and style of fonts in use, etc. This additional information will not generally be preserved in the email system, and may actually render the report unreadable at the receiving end. It is recommended that you create the report file at the very start of the Lab session. Keep a PFE subwindow open for the file throughout the session. In this way you can add notes to it as you go along. This then minimises the work required to complete the report at the end of the session. However: ensure that you save the report to disk every time you make any addition to it. Otherwise, if there is a power failure, or the PC crashes, you will lose all your notes up to that point. In writing the report (and in preparing email messages in general) limit your lines to about 65 characters wide at mostanything wider than that is apt to cause problems at the receiving end. Structure It is helpful, both for writing and marking, if the report can have a somewhat standardised layout or format. We cannot be too exact in giving a layout because different exercises may require a somewhat different approach. Also, the layout will have to be varied depending on the detailed problems or difficulties which you run into. Nonetheless, the following sections outline a preferred, generic, layout of the report, which you can use as a starting point. Note that these sections should be repeated as appropriate if the session is broken down into several separate exercises. Note that, while you can simply try to write the report sequentially, as the Lab progresses, you may well find that you sometimes want to backtrack, and revise an earlier section, or add some new information to it. This is where the computer scores over a paper Lab book: it is easy to back up and revise, or delete, or augment what was already entered. You should not get carried away with this freedom of course; but equally, you should not feel compelled to write the report in a pure sequential manner, in exactly the order you tackle the exercises during the session. Take a look at the skeleton report fileskelrpt.txt. This shows the overall layout of a report. You can use this as the basis for your own reports. Take a look at the skeleton report file (Appendix). This shows the overall layout of a report. You can use this as the basis for your own reports. Heading Each Lab Report must start with a standard heading as shown in the skeleton report fileskelrpt.txt. Edit in the appropriate information for the particular session. The Session Title should be filled in with the title as specified in the on-line notes. Plan Given the statement of an exercise for a particular Lab you should try to formulate an outline plan as early as possibleand record it in your report. This holds even if you subsequently have to severely modify (or even abandon) your plan. A plan should be a concise statement of how you intend to approach the exercise. The details will vary, of course, from case to case. But the plan will typically involve breaking the overall exercise into smaller, more managable pieces; experimenting with things you don't yet understand properly; identifying problems you anticipate; and perhaps an outline of how a program will be structured (what is technically called an algorithm). The lab instructions may well already outline a plan. But even in that case, you should consider whether you could usefully break down some of the steps suggested in the instructions into even smaller pieces. There will be no unique, correct plan. Some questions we will ask in assessing the report are: Did you make a plan at all? Is the plan clear and concise? Is it understandable? Is it practical? Is it internally consistent? Does it ultimately correspond with what was asked for in the instructions? A plan will normally be at most one paragraph. Subsequently in the report you can then describe progress compared to the plan. In particular, you can describe problems you encounter in following the plan, and any on-going changes you decide to make to it. Development This is the main section of the report. It should deal with your activities as you develop whatever program is required by the particular exercise. Development involves the following general kinds of activity: Coding: This is composing new code. Compilation: This is using the compiler to translate the code you have composedthe source codeinto the executable form that the CPU could directly execute. Execution: This is executing the program, and providing suitable test data, to assess whether, or to what extent, it behaves as required. It will generally be up to you to formulate satisfactory test cases. It is particularly important to try to test the limits of correct operationto test the program with extreme or exceptional input data, to assess whether it maintains correct behaviour in these cases. For example, if something is supposed to work over a certain range of numbers, make sure you test it at the limits of this range. If something is supposed to deal in a certain way with illegal input data, then actually test it on illegal input data to check this. It is unknown for development of any significant program to just go straight through these three phases one single time. Problems will invariably arise which mean that you must cycle back through these phases, possibly many many times, before a satisfactory version of the program is completed. Thus it is not appropriate for the Development section of the report to be simply divided into subsections for these distinct activities. Instead, it should be divided into subsections according to the successive problem(s) you find yourself dealing with. Thus, each subsection should try to clearly state a problem you are currently trying to solve, and your ultimate solution (if any!). A problem might be Code an initial version of the program, or Get rid of a compiler error message saying 'Unrecognised Symbol at Line 5' , or Test whether the variable x is being correctly updated or whatever. A problem will often be of the form that something is not behaving as you expected. In such cases try to be as clear as you can about what you expected and what actually happened. Distinguish between problems that are compile-timei.e. they are indicated by some message from the compilerand those that are run-timei.e. they are manifested only when the program is executed. The Development section must include the evolving text(s) of your program. As you make significant changes or additions to the program, you should include the new program textpossibly in whole, or possibly just those parts that have changed, whichever you judge is more appropriate. Conclusion The concluding section is concerned with summarising clearly and concisely what you achieved, relative to the assigned exercise. If you have learned anything new during the exercise, you can state that here too. Do not make any bald or simplistic claims to the effect that a program (or function etc.) worksexcept insofar as that is backed up by test results you have already given in the Development section. A program that merely compiles without error is a very long way indeed from one that works. Keep this distinction clear in your mind when writing this section. Do not try to pad this section out, or disguise some shortfall in completing the exercise. The marks here go for clarity, and honesty, not actual achievement! Including Source Files The exercises typically require that you create or modify one or more source files. You must include these source files, or relevant fragments of them in the Development section of your report. You should clearly delimit such files or fragments in the report (so that the program or fragment can be clearly distinguished from the text of the report proper), and explain exactly what they are. Here is an example: Note that, using PFE to edit the report, you can easily use the Copy and Paste facilities (on the Edit menu) to copy from one subwindow to another. Where you have created a new source file from scratch during the Lab session you should include the complete file in the report. Where you have only modified, or augmented, some given file then you should only include the modified parts, or the additions, in the report. You have to exercise some judgement here. The basic principle is that the report is a report on your work, so you omit anything which was already done for you; but you may have to bend this rule somewhat in order to provide enough context for the report to be understandable. In any case, the surrounding text of the report should make it clear what you have included, and why. Typically you will be developing one or more source files as the Lab progresses (correcting, debugging, enhancing etc.). So a natural question is whether you should separately include every single variant in your report. Again, this requires some judgement. The general principle is that the report should definitely contain the final versions of any relevant source file(s)i.e. as they were when you finished working on them. This is true regardless of whether this final version is actually functional or not. In addition to such final versions, the report should also contain earlier versions (or fragments of earlier versions) where that is useful or necessary to illustrate some significant problem or difficulty you encountered. This will be discussed further below. Problems Typically you will encounter one or more unanticipated problems in any given exercise. This is not a cause for alarm or dispair. We expect you to encounter problems: you would not have the opportunity to learn anything if you did not. Problems are opportunities for learningand opportunities for getting marks in your report! Note that this applies to the Lab exams just as to the normal exercises. We do not expect that you will be able to complete a exam without running into any problems. The central point of the exam is not to see whether you can avoid running into any problems, but whether you can effectively respond to whatever problems do arise. Some problems will be very minor and will not deserve reporting. For example, you leave out a semi-colon, or mistype a variable name. Provided these are easily and quickly fixed, you should omit them from the report. But, as a rule of thumb, any problem or difficulty which takes up anything in excess of 10 minutes of your time qualifies as significant, and something which must be described in the report. Remember: you can still get a very respectable mark on a report, even if you make relatively little progress in completing the given exercise - provided you can clearly explain what problem(s) you encountered and what steps you took to solve them. In fact, you will often find that the discipline of trying to explain clearly what your problem actually is often gives you an immediate insight into how to solve it! Problems are extremely diverse, and it is impossible to give a complete description here; but there are some specific kinds for which we can give more detailed advice. Problems of Understanding: For example, I don't understand what a matrix is, I don't know what type double means, I don't understand what for does, I don't understand what the given program SUPER.C is supposed to do. These are all perfectly good statements of a problem. The sorts of steps you can consider in trying to solve them include (re-)reading the relevant section of the textbook, (re-)reading the on-line notes, looking for information in the on-line documentation, trying something in isolation in a small test program to see what happens, asking a colleague, asking a demonstrator.Asking a colleague or demonstrator will not generally apply in a Lab exam of course; but even in that case you may ask for certain kinds of help - e.g. if you think the instructions you have been given are inconsistent or impossible to carry out. Compilation Problems: If messages are thrown up when you attempt to compile a program, then these definitely constitute problems. Some may be trivial, as already discussed; but some may be very difficult, in which case they should be discussed in the report. In that case, you should include, verbatim, at least the first message which is coming up, together with enough of the program file to see the context in which the message is appearing. Strategies for solution include: trying variations in the program to see what effect these have on the message(s); using the on-line documentation to try to get more, or better, information; trying to find a different way of programming whatever it was you wanted to program. And so on. Run-time Problems: These are generally of the form I ran this program, gave it this data, and this (unexpected) thing happened. Note carefully that an adequate description of this kind of problem requires you to say clearly what the expected or correct behaviour would have been. In fact, it will sometimes turn out that the solution to this kind of problem will be to recognise that you were mistaken in what you expected (i.e. the program is actually behaving correctly). In any case, solution strategies for this kind of problem include: rerunning the program with the same data (to see if the symptoms are repeatable); rerunning the program with different data (to see if a pattern of failure can be built up); adding extra code to the program to get more information on what's going wrong; cutting down the program to try to localise the problem. And so on. Equipment Problems: You may encounter problems with the lab equipmenthardware or software. These will typically be outside your control to fix. But, if such a problem has impacted significantly on doing the exercise, you should include it in the report. In particular, you should explain what the symptoms were, why you classified it as an equipment problem, and how long it took for it to be sorted out. Marking Scheme The following general principles will apply: The report should be clear, concise, and reasonably professional. That is, there should not be too many errors of presentation (grammar, spelling, etc.). The style need not be too formal (e.g. you can use the first personI did this.., I tried that... etc.) if that is what suits you. However, you should not be too informal either (e.g. using slang terms etc.). The report should follow the general outline detailed in previous sections. Full marks will be awarded only where all the elements asked for in the instructions have been successfully completed, tested, and adequately described in the report. Marks will generally be deducted if a report is too long, and, in particular, if it repeats significant extracts from the on-line notes. Where a session involves several distinct parts or exercises, the instructions will state how the total marks are allocated between these exercises. Within each such part or exercise, marks will be allocated as follows: Plan: 10. In more detail: this will be awarded on a qualitative assessment of whether the plan is coherent, whether it is appropriate, whether it deals adequately with the exercise as stated etc. It will not depend on whether you actually succeeded in carrying out the plan! Development: 60 10 will be awarded for presenting code which is even approximately correctcorrect in outline. A further 10 is awarded if the code is free of syntactical errors (i.e. compiles successfully)or if the report gives a good explanation of what syntactical errors are still present, and what steps were taken in trying to solve them. A further 10 is awarded for program stylewhether the code is sensibly indented, with good line breaks, sensible spacing, meaningful identifiers, and effective comments etc. 10 will be awarded simply for specifying, in detail, suitable run time test cases: i.e. tests to be carried out, and the (correct) expected behaviour. 10 will be awarded for presenting actual execution time results for these casesclearly stating, in each case, whether the test was passed. A further 10 will be awarded if the program passes all such test cases, or if the report gives a good explanation of what errors are still present, and what steps were taken in trying to correct them. Conclusion: 10 These marks will be awarded provided the conclusion is a clear, concise, and accurate summary of what was achieved and/or learned. Bonus: 20 The final 20 is reserved as a bonus to be awarded entirely at the discretion of the marker. These marks will be awarded for particular excellence of various sorts. For example, where the report is particularly well written and presented; where the testing has been particularly comprehensive; where the code is particularly elegant; or where the report demonstrates particularly good problem solving skills. This last is especially important: the point being that, even if you get mired down in difficulties, and make little progress on the assigned exercise, you might still qualify for some or all of this bonus if you can demonstrate that you adopted an effective, logical, structured and systematic approach to trying to sort out the difficulties. Copyright This Hypermedia Document is copyrighted, 1995, by Barry McMullin http://www.eeng.dcu.ie/7Emcmullin/home.html. Permission is hereby granted to access, copy, or store this work, in whole or in part, for purposes of individual private study only. The work may not be accessed or copied, in whole or in part, for commercial purposes, except with the prior written permission of the author. *Appendix: Skeleton Report File