Updated March 8, 2014 to discuss the use of GPL licenses.
This page discusses general procedures for implementation assignments and extra credit projects. See the individual assignment pages for details.
There will be three implementation assignments. These will involve writing Java implementations of abstract data types and associated algorithms, and testing the implementations on sample data. You will also provide instructions on how to compile and run the program, document your design and implementation (including complexith analysis), and present and discuss test results. The assignments will progressively give you more responsibility. For the first project, you will be told what to implement, and it will be weighted 6% (60 points). For the second assignment you will need to make some implementation choices. The second assignment will be weighted 10% (100 points). The third assignment will require some research and decision making on your part to solve the problem. It will be weighted 10% (100 points).
The following requirements have been adopted from Dr. Sugihara:
All software must be written in Java. Other programming languages may not be used except where specified by the assignment.
The software must be compilable on the default version of Java available on uhunix.hawaii.edu at the time of the submission deadline. The reason for this is to ensure that there is a common reference environment against which we can resolve disputes. We can’t grade projects on claims that “it compiled on my machine”.
Uhunix is running Solaris. At this writing, the Java version is:
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) Server VM (build 24.51-b03, mixed mode)
Projects submitted with higher versions of Java (if they become available) are at your risk. Note that the instructor is presently running research projects in Java 1.6 in Snow Leopard on which Java 1.7 is not available. Some features of Java 1.7 do not compile in 1.6, so if you could stick to 1.6 features he won’t have to go to UH Unix to run your code.
The software should run as a Java application.
The student shall submit .java source files (not class or jar files), organized in folders as required for your package structure, along with instructions for compiling the program and other documentation discussed in the next section.
Source files should include the BSD License Header based on this
template, with “
Other open source licenses (e.g., Apache or GNU) may be used with prior permission from the instructor if the student has a specific reason for doing so and understands the consequences. See the discussion under Other Licenses two sections below.
Source should include appropriate in-line comments documenting the software design. Comments should not document the obvious (e.g., “this line adds 1 to the index variable”), but rather document functional intent and constraints such as loop invariants, explain something that would otherwise be obscure, mark places that need improvement, etc. Descriptive use of variable and method names also constitutes internal documentation. See next section for external documentation requirements.
Each assignment will specify where you are allowed to reuse source code of open source software developed by other authors, and where you must write your own code for the assignment. Where allowed by the assignment, reuse of open source code is allowed if the following conditions are also met:
Readme.txt of your product clearly gives credit to the authors of the reused source code (i.e., including information such as the name of an author, the name of a reused product and a list of file names of the reused source code).When source code of a module is reused, add the name(s) of its original
author(s) to an @author tag at the beginning of the reused module. If you
modified the source code for more than bug fixes, add your name as an author
of a derivative from the original source code:
/**
*
* @author Original Author James Brown
* @author Derivative Author Robert Smith
*
*/
I am often asked whether one can use code under another license. You may use other open source licenses as long as (1) they give you the right to use the code under conditions acceptable to you and (2) you document this as needed. An example is the GPL license. You may use a GPL compatible license, but you use this license, all the code you write must also be under GPL. See http://en.wikipedia.org/wiki/Free_software_license for an overview, and read some blogs about this hotly debated issue.
Software will be submitted with appropriate documentation, including the following. (Think of your audience for this documentation as any potential users, including your classmates as well as the TA and instructor.)
Readme.txt (plaintext file)
Critical information that a user should know about your product first, including:
Operation Manual (plaintext or PDF)
Concise, yet sufficient step-wise explanation about how to start and interact with the program, written for an end user who is concerned with using the program in an application domain (not with the code).
Reference Manuals (plaintext or PDF, and Javadoc HTML)
Requirements and design specifications; organization of modules; algorithms and data structures used; functionality of each class or method; etc. A reference manual is written for experienced users and/or programmers who perform various maintenance activities for correction, enhancement, adaptation, etc. Javadoc pages may also be included, and should be included if you intend to have others use your code.
Testing Document (plaintext or PDF)
Test plan describing objective(s) of testing, method(s) used for testing, assumption(s) of testing, and hardware/software environment in testing; test case specification describing classification of test cases; test data and I/O of test runs; and whatever else is useful to convince other people about the correctness and good features of your program. For ICS 311 assignments the testing document will include your conclusions related to the purpose of the assignment.
These are our default grading criteria. Some adjustments may be made when we see where the greatest effort is required.
Program: 60%
5% for adequate error handling. Analysis and Documentation 40%
If others elect to use your software in a subsequent assignment (e.g., using your graph ADT implementation in the third assignment), we will give extra credit. See discussion in Assessement page. Use should be credited in the Readme and Reference Manual.