Informatics 2 - Software Engineering - 2017/18
Coursework 3
To get started, you will need
- The coursework handout
History
- Sun 12 Nov 2017. v4. Added sentence to Section 2.6
documenting the output expected by the provided test code when a
new tour is being created.
- Fri 10 Nov 2017. v3. Added a new section, Section
4.6, clarifying what provided skeleton code can and cannot be
altered.
- Fri 10 Nov 2017. v2. Fixed class named in Section 7
that needs Javadoc comments.
Adjusted slightly the description of singleton classes in Section 4.5. Fixed a few minor grammatical errors.
- Wed 8 Nov 2017. v1. Initial release.
- The skeleton project code: tourguide-skeleton.zip
History
- 11:15 Sun 12 Nov 2017. Fixed constructor of
Chunk.FollowHeader class. Renamed numberPositions field of
Chunk.CreateHeader class to numberWaypoints in order to make
intended use of field clearer.
- 10:40 Thu 9 Nov 2017. Fixed toString() method of
Chunk.CreateHeader class.
- 17:00 Wed 8 Nov 2017. Initial release.
Additional information important for completing the project will be
posted below. When changes are made the Change Log entry below will be
updated and an email sent out to the class.
Change Log
Writing Javadoc comments
Java reference documentation lists a number
of kinds of tags one can use in Javadoc comments. Some of the most important are @param
for method and constructor parameters and
@return for method return values. For this coursework it is
sufficient to just use these two kinds.
The Coursework 3 handout says in Section 3.1 "add class-level, method-level and field-level
Javadoc comments to the provided Displacement class". As the
Displacement class methods all have no parameters, please also add a
Javadoc comment for the Displacement constructor which does have parameters.
Oracle's
guide to writing Javadoc comments is worth browsing, but provides much more detail than
is needed for this coursework. It is sufficient to just skim the "Introduction"
section and, in the "Writing Doc Comments" section, to just take a look
at:
Using Eclipse or some other IDE
It is strongly recommended that you use Eclipse or some other IDE for
developing your code. Useful features include refactoring support to
keep your code clean, JUnit support, automatic recompilation, and an integrated
debugger where setting breakpoints and checking program state is quick
and simple.
If you use Eclipse you can get started as follows:
- As in Section 4.2 of the handout, download the "tourguide-skeleton.zip" file and unzip it in
some temporary location in your file-space to create a directory
tree with top-level directory "TourGuideSkeleton".
- Start up Eclipse. These instructions have been tried out using
Eclipse Oxygen (4.7.0) on DICE and Oxygen.1 (4.7.1) on a Mac. Very likely something similar works with
other versions and on other platforms.
- In Eclipse, create a new Java project using File > New > Java
Project. This opens up the first page of the new project
wizard.
- Choose a "Project name" for your project, ideally without
spaces. Here will assume the name is "TourGuide".
- Choose JRE JavaSE-1.8 for the execution environment.
- Select "Create separate folders for sources and class files".
Click "Configure default..." to check the source folder is "src" and
the output folder name "bin". Click "Apply and Close" on this "Preferences
(Filtered)" page.
- Click "Next >". On the "Source" tab (the tab you are taken to),
tick the box "Allow output folders for source folders".
- Click "Finish" to create an TourGuide project folder in your
Package Explorer view with a "src" subfolder.
- Select File > Import. In "Import" pop-up window,
select General > FileSystem. Click "Next".
- In the "File system" box use the "Browse" button to select the
TourGuideSkeleton directory created from the unzip. In the white box
below, tick the box by "TourGuideSkeleton". The "Into folder" should be
set to "TourGuide".
Click "Finish". With Oxygen.1 (4.7.1) on a Mac there is a glitch
at this stage. See below for the workaround.
When all goes well, you should now see in the
Package Explorer the full "src", and "lib"
directory trees. Assuming you have autobuilding enabled, the source
files will not compile properly because JUnit library information is
missing. The next step is to provide this information.
- Select your TourGuide project directory in the Package explorer
and open a Properties window for the project using Project >
Properties. Select the "Java Build Path" property, select the
"Libraries" tab and click "Add JARs...". Select both the JUnit and
the Hamcrest ".jar" files in the "TourGuide/lib" directory and click
OK, then click "Apply and Close" in the Properties window.
- The Java source files should now all compile fine, and you
should be able to both run individual JUnit tests and the
AllTests class as a Java application.
Importing on a Mac with Oxygen.1 (4.7.1)
In step 10 when importing the skeleton files, it looks like the
"TourGuideSkeleton" directory has been found, but,
on clicking "Finish", one gets a pop-up "Information" window with
the message "There are no resources currently selected for
import". The workaround is
- click "OK" to dismiss this pop-up,
- untick the tick box you just ticked next to "TourGuideSkeleton" in
the left big white box
- click at the end of "TourGuideSkeleton"
in the "From directory:" box and
hit return. A triangle now appears next to "TourGuideSkeleton"
that allows one to browse the imported files.
- Now tick again the tick box by "TourGuideSkeleton" and click
"Finish".
Tabs, indents and line lengths in Java code
The handout recommends you follow standard coding guidelines such as
those from
Google
or Oracle/Sun.
A common recommendation is that you never use tab characters for
indentation and you restrict line lengths to 80 or 100 characters.
You are strongly recommended to adopt both these recommendations, both
because it is good practice and, particularly, in order to ensure
maximum legibility of your code to the markers. I recommend using an
indent step of 4 spaces as in the Sun guidelines rather than the 2 in
the Google guidelines, for consistency with the supplied code.
The default in Eclipse is to use tab characters for indents. To
change this, open the Preferences pop-up and navigate to the
Java > Code Style > Formatter preference. Edit the
existing Profile to create a new Profile that only uses spaces.
Say name the new profile "Eclipse no-tabs".
In Eclipse, you can check the right margin setting and turn on a right
margin indicator line by visiting the
General > Editors > Text Editors preference.
Version control
You might well want to take this opportunity to try using version
control for your project. If nothing else, this will back up your
code and make it easy to work on shared code. There are a number of
free repository hosting services available on the web.
If you are new to version control, you might find it easier to start with
subversion rather than git or mercurial.
If you do use a repository hosting service, it is vital that you
choose one where your code is private to your coursework group, not
open for anyone to read.
See the School's advice on good scholarly conduct.
Note that many free hosting services are geared
towards supporting open-source projects and do not provide the
option of making your repository private. For example, normal free GitHub repositories
are not suitable, as they are world readable.
However, the
GitHub Student Developer
Pack does offer students the opportunity to create free private repositories.
And a popular provider of
free git-based private repositories is bitbucket.
There is no coursework requirement that you use any version control system and no
extra marks will be given if you do.
