Below you find a number of guidelines that is the basis for a good report describing how you have solved a certain assignment. This report is what you should hand in to the assistants. However, special demands formulated in the assignment might higligt different parts.

Purpose of a report

• Exercise your writing skill
• Document your work in a professional and formal correct way
• Make it possible for others to understand your work
• Prepare for comming professional work where documentation is important

Content of a report

• Cover sheet
• Abstract
• Content
• Problem Specification
• Usage and user's guide
• Algorithm Description
• Systems Description
• Limitations on the Solution
• Problems and Reflections
• Test runs
• References
• Source Code
• Attachments

Cover sheet

See Example here.

Abstract

• Normally not needed, but if the report is large and made by a group an abstract might be good.

Content

• A listing of all chapters and sections
• Even attachments (if present)

Problem Specification

• Describe what is to be done (what should be solved)
• Use your own words, i.e. do not copy the assignment specfication
• Refere to the original assignment specification
• If the original specfication is incomplete - note that and state what assumptions you have made

Usage and user's guide

• Say where your files are stored, normally that is said in the specification of the assignment.
• If several files are used you should shortly describe their purpose
• Describe how your code should be run. Describe every possible argument provided by the command line

Algorithm Decription

• Describe non-trivial parts of the solution by using English/Swedish
• Use a numbered list in several levels to indicate subparts
• Try, not to use variable names and units linked to the code. However, it is OK to use some "reserved words" such as while, for, if-then-else that seems natural in connection with repetetion and if-questions
• The purpose of this section is that a reader should understand how you have solved the problem without knowing about the details
• Design your algorithms before you start coding!!!!!!>

Systems Description

• The most central part of the report
• Should describe the internal design and structure of the total system
• What is considered importatnt might vary - ask the assistants if you are uncertain
• It is better with many small figures, and a description of how they interact than one big spider net that is almost impossible to follow
• Object-oriented development (Java and more):
  • Describe relations between classes with figures and comment on these
• General guidelines
  • Describe every function, its name, input/output, purpose
  • All user defined data types and structures should be described

Limitations on the solution

• Describe all limitations you can think of when solving this problem
• How can the limitations be avoided?

Problems and Reflections

• What problems have you run into?
• What is your oppinion of the assignment?
• If some persons have been especially helpful? Acknowledge these persons

Test Runs

• Show output data typeset by courier
• Comment on the tests. What is tested? Interprete the results

References

• Normally not included

Source code

• It is a good idea to attach the source code to the report
• The code should be printed by using Courier
• Use indentation in a good way
• Use e.g. atp, a2ps and enscript) to print the code nicely
• Use comments in the code where it is not obvious what it does
• Describe every function, its name, input/output, purpose

Attachments

• Some times used

General comments

• The logo of Umeå University should not be used
• Use correct and plain English or Swedish
• Use a footer including your name, E-mail address, name of the course and Assignment #
• Number the pages (paginate)
• The pages of the report should be attched to each other
• Use spell checkers

Sidan skapades av Marcus Bergner, bergner@cs.umu.se
and was translated by Per Lindström