% swe1root.tex
%
% Lab Report Guidelines for Software Engineering 1.
%
% This is prepared as a LaTeX file, but is actually intended to
% be processed into HTML, using latex2html, for access via WWW.
%
% Barry McMullin, November 1994.
%

\documentstyle[html,12pt,a4]{article}

\newcommand{\C}{{\bf C}}
\newcommand{\atwork}{\htmladdimg{at_work.gif} (Under Construction...)}

\newcommand{\tty}[1]{{\bf #1}}
\newcommand{\qt}[1]{``#1''}
\newcommand{\mdash}{---}

\begin{htmlonly}
\renewcommand{\tty}[1]{{\bf #1}}
\renewcommand{\qt}[1]{"#1"}
\renewcommand{\framebox}[1]{#1}
\renewcommand{\mdash}{~-~}
\end{htmlonly}

\newcommand{\hot}[2]{\htmladdnormallink{#1}{#2}}
\newcommand{\hotfoot}[2]{\htmladdnormallinkfoot{#1}{#2}}

\sloppy

\begin{document}

\title{Software Engineering 1: Laboratory Report Guidelines}
\author{Barry McMullin}
\date{Last Modified: 28th March 1996}

\maketitle

This document gives guidelines for the Laboratory Reports submitted for
the course
\hotfoot{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 {\em 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:
\begin{quote}
\hot{SOFTENG1-95@mjmail.eeng.dcu.ie}
{mailto:softeng1-95@mjmail.eeng.dcu.ie}
\end{quote}

\section{General}

The {\em Software Engineering 1} Lab reports are submitted using email. This
implies, of course, that they must be {\em 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 \hotfoot{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 {\em Software
Engineering 1} is that they should explain {\em where your time went}
during the lab session.  If you successfully completed the assigned
exercises, this can be relatively straightforward\mdash copies of the file(s)
you created or modified, details of the tests you carried out and their
results. The difficulty arises where you do {\em 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 others\mdash and so on. The point is
that, if you spend three hours in the Lab, you {\em must} have done {\em
something}: so report on what that something was, no matter how far
removed it may seem from what was actually requested.

\section{Typing Up}

The reports must be prepared and submitted
{\em during} the Lab session.

It is recommended that you use \tty{PFE} to prepare the report.
Do {\em not\/} use any wordprocessing package such as
\tty{Write}, or \tty{MS-Word} etc.\footnote{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 \tty{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.

{\bf 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 most\mdash anything wider
than that is apt to cause problems at the receiving end.

\section{Structure}

It is helpful, both for writing and marking, if the report can have a
somewhat standardised layout or format.  We cannot be {\em 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 {\em 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.

\begin{htmlonly}
Take a look at the \hot{skeleton report
file}{skelrpt.txt}. This shows the overall layout of a report. You can
use this as the basis for your own reports.
\end{htmlonly}

\begin{latexonly}
Take a look at the {\em skeleton report
file} (Appendix). This shows the overall layout of a report. You can
use this as the basis for your own reports.
\end{latexonly}

\subsection{Heading}

Each Lab Report must start with a standard heading as shown in
the \hot{skeleton report file}{skelrpt.txt}. Edit in the
appropriate information for the particular session. The \tty{Session
Title} should be filled in with the title as specified in the on-line
notes.

\subsection{Plan}

Given the statement of an exercise for a particular Lab you should try
to formulate an outline {\em plan} as early as possible\mdash and 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 {\em 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, \qt{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
\qt{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.

\subsection{Development}

This is the main section of the report.  It should deal with your
activities as you {\em develop} whatever program is required by the
particular exercise.  Development involves the following general
kinds of activity:

\begin{itemize}
\item Coding: This is composing new \C\ code.
\item Compilation: This is using the compiler to translate the \C\ code
you have composed\mdash the {\em source} code\mdash into the executable form
that the CPU could directly execute.
\item 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 {\em limits} of correct
operation\mdash to 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 {\em limits} of this range.  If
something is supposed to deal in a certain way with \qt{illegal} input
data, then actually test it on \qt{illegal} input data to check this.
\end{itemize}

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 {\em
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 {\em 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 \qt{Code an initial version of the program}, or \qt{Get rid
of a compiler error message saying 'Unrecognised Symbol at Line 5' }, or
\qt{Test whether the variable \tty{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 \qt{compile-time}\mdash i.e. they are indicated by some message from the
compiler\mdash and those that are \qt{run-time}\mdash i.e. they are manifested only
when the program is executed.

The {\em Development} section {\em 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 text\mdash possibly in whole, or
possibly just those parts that have changed, whichever you judge is more
appropriate.

\subsection{Conclusion}

The concluding section is concerned with summarising
{\em clearly} and {\em 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 {\em not} make any bald or simplistic claims to the effect that a
program (or function etc.) \qt{works}\mdash except insofar as that is backed
up by test results you have already given in the {\em Development}
section.  A program that merely {\em compiles} without
error is a very long way indeed from one that {\em works}. Keep this
distinction clear in your mind when writing this section. Do {\em 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!

\section{Including Source Files}

The exercises typically require that you
create or modify one or more \C\ source files. You must
{\em include} these source files, or relevant {\em fragments} of them in
the {\em 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:

{\small
\begin{verbatim}

        This is the program BDAY.C . It is a modified version of
        the program XMAS.C from page 4063 of the textbook. It prints a
        birthday greeting.

        --------------------------------------------

        /* BDAY.C */

        #include <safe-c.h>

        int main(void)
        {
          put_string("Happy Birthday!!!");
        }

        --------------------------------------------

\end{verbatim}}

Note that, using \tty{PFE} to edit the report, you can easily use the
\tty{Copy} and \tty{Paste} facilities (on the \tty{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 {\em 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 {\em definitely} contain the
\qt{final} versions of any relevant source file(s)\mdash i.e. as they were
when you finished working on them.  This is true {\em regardless of
whether this \qt{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.

\section{Problems}

Typically you will encounter one or more unanticipated \qt{problems} in
any given exercise.  This is {\em not} a cause for alarm or dispair.  We
{\em expect} you to encounter problems: you would not have the
opportunity to learn anything if you did not.  Problems are
opportunities for learning\mdash and opportunities for getting marks in your
report!

Note that this applies to the Lab {\em exams} just as to the normal
exercises.  We do {\em not} expect that you will be able to complete a
exam without running into any problems.  The central point of the exam
is {\em not} to see whether you can avoid running into any problems, but
whether you can effectively {\em 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 {\em must} be described in the report.

Remember: you can still get a very respectable mark on a report, even if
you make relatively little \qt{progress} in completing the given exercise
- {\em 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 {\em 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.

\begin{itemize}

\item {\bf Problems of Understanding}: For example, \qt{I don't understand
what a {\em matrix} is}, \qt{I don't know what {\em type double} means},
\qt{I don't understand what \tty{for} does}, \qt{I don't understand what
the given program \tty{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.\footnote{Asking a colleague or
  demonstrator will not generally apply in a Lab {\em exam} of course;
  but even in that case you may ask for {\em certain} kinds of help -
  e.g. if you think the instructions you have been given are
  inconsistent or impossible to carry out.}

\item {\bf 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.

\item {\bf Run-time Problems}: These are generally of the form \qt{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 \qt{expected} or \qt{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 {\em you}
were mistaken in what you expected (i.e. the program is actually
behaving \qt{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.

\item {\bf Equipment Problems}: You may encounter problems with the lab
equipment\mdash hardware 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.

\end{itemize}

\section{Marking Scheme}

The following general principles will apply:

\begin{itemize}

\item The report should be clear, concise, and \qt{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 person\mdash \qt{I did this..}, \qt{I tried
that...} etc.) if that is what suits you.  However, you should not be
too informal either (e.g. using slang terms etc.).

\item The report should follow the general outline detailed in previous
sections.

\item Full marks will be awarded only where {\em all} the elements asked
for in the instructions have been successfully completed, tested, and
adequately described in the report.

\item Marks will generally be {\em deducted} if a report is too long,
and, in particular, if it repeats significant extracts from the
on-line notes.

\end{itemize}

Where a session involves several distinct parts or exercises, the
instructions will state how the total marks are allocated {\em between}
these exercises.  {\em Within} each such part or exercise, marks will be
allocated as follows:

\begin{itemize}

\item {\bf 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 {\em not}
depend on whether you actually succeeded in carrying out the plan!

\item {\bf Development: 60\%}

10\% will be awarded for presenting code which is even approximately
correct\mdash correct in outline. A further 10\% is awarded if the code is
free of syntactical errors (i.e. compiles successfully)\mdash {\em 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 {\em style}\mdash whether the code is
sensibly indented, with good line breaks, sensible spacing, meaningful
identifiers, and effective comments etc.

10\% will be awarded simply for {\em 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 {\em results} for these cases\mdash clearly stating, in each case,
whether the test was {\em passed}. A further 10\% will be awarded if the
program passes all such test cases, {\em or} if the report gives a good
explanation of what errors are still present, and what steps were taken
in trying to correct them.

\item {\bf Conclusion: 10\%}

These marks will be awarded provided the conclusion is a clear, concise,
and accurate summary of what was achieved and/or learned.

\item {\bf Bonus: 20\%}

The final 20\% is reserved as a \qt{bonus} to be awarded entirely at
the discretion of the marker.  These marks will be awarded for
particular {\em 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 {\em 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.

\end{itemize}

\section{Copyright}

This Hypermedia Document is copyrighted, \copyright\ 1995, by
\hotfoot{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 {\em not\/} be accessed or copied, in whole or in part, for
commercial purposes, except with the prior written permission of the
author.

\newpage
\appendix
\section*{Appendix: Skeleton Report File}

\footnotesize
\begin{verbatim}
----------------------------------------------------------------

                        SOFTWARE ENGINEERING 1

                        ACADEMIC YEAR 1995/96

                          LABORATORY REPORT

----------------------------------------------------------------

Student Name:    Barry McMullin
ID Number:       96123456

Session Date:    9th November 1995
Session Number:  3
Session Title:   Introducing C

----------------------------------------------------------------

Exercise 1: Hello World!
------------------------

Plan
----

Development
-----------


Conclusion
----------

----------------------------------------------------------------

Exercise 2: Branching Out.
--------------------------

Plan
----

Development
-----------


Conclusion
----------
\end{verbatim}

\end{document}
