[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