Finishing Your COM1204 Project -- Spring 2001

Professor Futrelle -- College of Computer Science, Northeastern U., Boston, MA

(Version of 5/24/2001)


Due date, time

Your projects will be due, electronically, by midnight, Thursday, May 31st. I would urge you to finish on time. The serious penalty for being late could be that you have less time to study for your final exams in all your courses, because of your project work for this one course. This due date is almost one full month after your previous work was due. So you have had a lot of time to continue to work on your project since then. I certainly hope you've made some progress!

What to hand in and how to hand it in

Send email to both jshan@ccs.neu.edu and futrelle@ccs.neu.edu with the locations of your files and javadoc pages. Do not put any details about your project in your email. All grading will be based on the files pointed to by your email. All files should be copied to your web space so we can reach them via URLs. Always include complete URLs such as, http://www.ccs.neu.edu/home/futrelle/teaching/com1204sp2001/finishing/Toy.java That is, you should make it possible for us to click on such a URL in your email and have the files or html pages appear immediately in our browser. If you want to connect us to a web page that has all the links we need, that's fine too. We have found that when students scatter their materials around in different directories, we have to move around in unix directories and cat or more the files to the screen or ftp in and transfer the files. For 55 students, with files scattered all over, this is quite inefficient. That is why we are requiring the more orderly approach above.

Overall goal - Design and documentation

Your goal for this final stage of the project should not be to write more code, but to organize and document the code you have already written. (The only exception to this would be if you've only managed to produce a very small amount of code so far. In that case you will need to produce more code. Check with us right away if you're in doubt.) The level of disorganization in much of the code and documentation developed by the students in this course to date has made it difficult to properly evaluate what you have done. There are numerous suggestions, guidelines and examples below that should help you in revising what you have done so far.

You should feel free to use any of the javadoc elements that I have used in my Toy.java example discussed below. I use various html tags to format the javadoc comments in a more readable form.

Broad Overview of what you should attempt to accomplish

(Suggested titles are in bold. Details follow in further sections below.)

Organizing your code

Javadoc and code example

The example shows the Javadoc comments that might accompany a class definition. Here is the Java source text itself, Toy.java, and here is the collection of Javadoc pages it generates. I have attached a number of comments to the class as a whole to avoid having them spread across all the methods. In addition I have annotated some of the methods. It is important to comment the methods, especially methods that, in turn, invoke methods in other objects. There is no standard place in Javadoc to mention these other method calls, but they are important in a simulation that involves the interaction of different modules (and for that matter, in almost any complex system, whether a simulation or not).

Javadoc -- commenting methods

The comments for step() are rather extensive since it is so important for many of the modules and its actions need to be explained. The methods called by a public function such as step() are normally private, so their Javadoc comments would not normally appear in an API for a class. They can be revealed by using the -private option when invoking javadoc. These private methods should in addition have Javadoc comments that mention any methods that they invoke on other objects. This helps explain module interactions. There will be some duplication, since the public methods in the other objects will also explain their purpose and use, but such redundancy could be useful. Not every suggestion I've given here has a corresponding example in the javadoc linked to this page, but a reasonable number do.

Comments for public methods of a class can confine themselves to the operation of the method itself, since they do not call methods on other objects (Rule 2).