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

• Overview Produce one document that serves as a brief guide to what you have done and how you accomplished it. You may include an "Afterward" describing what you might like to do next or how you would have preferred to see the entire project organized, or any other comments you deem relevant.



• Working arrangements Include an explanation of how you were (or were not) able to work within your group or with specific individuals. State carefully what you did and what others did.



• Program structure In a separate overview document, explain the structure of your program modules, how they function and interact.



• Organize your code in a modular fashion.



• Produce readable, understandable source code, with both Javadoc and other comments, as need.



• System testing Explain the design of your tests and comment on the results your tests give.



• Put your name and date on every document you produce that we might read.

Organizing your code

• Basic rule #1: step() may cause calls to methods in other modules (typically only one). By this we mean, for example, the ph1.step(), where ph1 is a phone instance, might cause phone to invoke some method of its ether object, e.g., to deposit or retrieve a message from the ether.



• Basic rule #2: A call to any public method of an object other than step() should only cause additional internal calls and setting of state variables, e.g., reducing a countdown value. Thus, the call on the ether in the rule 1 example above would not cause further calls by the ether on any other module -- only a step() of the ether could cause that.



• Motivation for rules 1 and 2: These rules reduce the number of different possible actions that can result during a single time step. If there were no such rules, deep sets of nested calls might result from a single step() call, that would be attempting to produce activity that could go beyond what should happen in a single time step.



• Modularize your code by keeping your methods reasonably short and having them call other methods. See the examples below.



• Produce readable, understandable source code, with both Javadoc and other comments, as need. See the examples below.



• You should explain the design of your tests and comment on the results your tests give. These comments can be in a separate document as well as added to your test files after they are produced, interspersed with your test results. Some of the points to make here are:
  
  
  • What you were attempting to test.
  
  
  
  • How you did the tests.
  
  
  
  • What did the results demonstrate? That is, analyze and evaluate the results that your tests produced. Though the results may seem self-evident to you, they may not be to another reader.
  
  
  

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).