PI: Non-Laboratory 5: Study, Document, Revise
Introduction
This assignment emphasizes the following topics:
- Software lifecycle, especially revision
- Documentation
- Independent learning
You should read through this entire assignment before beginning any of it. This assignment is actually two one-week assignments. However, given some of the scheduling complexities, we're going to let you decide when you want to do each part. Manage your time carefully as the total assignment should fit reasonably into the two weeks alotted, but it is a lot to do in one week. You will need to make decisions about how to allocate your time over the next two weeks. Certain parts of this assignment require multiple steps to carry out or are done at specific times.
The schedule for the next week or so is somewhat unusual:
- Monday, 6 October: No scheduled lab, but course staff will hold open office hours in the lab during the scheduled time.
- Tuesday, 7 October: Class as usual.
- Wednesday, 8 October: No problem set due. (Original deadline for Parts 1 and 2 of this assignment.)
- Thursday, 9 October: Olin Career Initiatives Day. No class.
- Friday, 10 October: Olin Monday. Lab session for Part 3 of this assignment. If you cannot make this session, please email us ASAP.
- Monday, 13 October: Columbus Day. Yes, you heard right: a holiday.
As usual, you are encouraged to collaborate on this assignment. In particular, you are encouraged to behave as "peer critics" of one another's code, much as you would peer edit an essay. You should be sure that everything you turn in is your own work, but it is great if that work is informed by the comments of your peers. You should alos, of course, acknowledge the contributions of your peers. Please include the names of anyone with whom you collaborate, in any way, on this assignment, and indicate the nature of the collaboration. If you do not collaborate with anyone, please say so explicitly. [Failure to include this information is a violation of the collaboration policy.]
All parts of this assignment are due at 5pm on Wednesday, October 15th, to the pi-homework mail-in.
Contents
- Introduction
- Part 1: Independent Study
- Part 2: Documentation and Code Understanding
- Part 3: Code Revision
- What To Turn In
Part 1: Independent Study
For this part of the assignment, you will need to identify a Java topic about which you'd like to know more. If you are feeling shaky about something we've nominally covered, this would be a good time to explore it further and solidify your understanding. If you are confident about all of your knowledge to date, you can choose a new topic to understand. For those students who want to explore something new, I particularly recommend the topic of Inner Classes. (Note, however, that understanding inner classes is very difficult if you do not have a good handle on the topics we've covered to date.) A less ambitious new topic is Collections. Do not choose GUI (AWT or Swing) or networking.
Your job is to identify a resource that covers the material you've selected. You may do this in one of two ways:
- Find a Java (text)book in the Olin Library. These books were chosen explicitly because they provide good alternative views of Java topics. Select a relevant chapter from one of these books.
- Browse the web. There are lots of good Java resources on the web. Sun's website (java.sun.com) is a good place to start, but Google will give you many more choices if you try, e.g., java tutorial.
Members of the course staff will be happy to suggest a topic if you cannot readily identify one. Also, we have some textbooks in the Computers and Cognition Laboratory, but these are a more mixed bag than the library's collection. CCL books must be used in the CCL or signed out explicitly.
Select your reading. It should be approximately one chapter from a book or a similarly sized tutorial topic. Read it. Then create a simple explanatory aid aimed at other Java students. This aid may be a web page, a diagram with explanation, a poster, a program with explanatory text.... It need not stand alone; you can assume that the students in question are enrolled in a course. Also include a separate paragraph explaining what you learned from this exercise. Be sure to cite the source you used (as well as any collaborators, of course)!
NOTE: This entire exercise (reading and constructing the aid) should not take more than 6 hours; I expect it will take most students 4 to 5 hours if the topic and scope are appropriately chosen.
Part 2: Documentation and Code Understanding
For the second part of this assignment, we are providing three code files: MysteryBall.java, GeminiBall.java, and SiblingBall.java. These are all Ball implementations suitable for use with BallWorld. (And you thought that you were done with BallWorld!) None of these files is properly documented. In fact, the style in MysteryBall.java is downright sloppy.
Your job is to fix someone else's code. Specifically, you should improve MysteryBall.java so that it is significantly more readable. You don't neeed to change the behavior of the code, but you certainly need to change the documentation. There are also stylistically ugly things in the code and you should fix these as well. If you wish, you can modify and improve MysteryBall.java, but this is absolutely not necessary.
In addition, for students who would like a bit more experience reading and understanding code, the pair of files GeminiBall.java and SiblingBall.java are provided for your reading and documenting pleasure. The logic of this code is somewhat more complex than MysteryBall's and students who would rather spend their time strengthening their understanding of what we've already covered are not obliged to work with GeminiBall and SiblingBall. (In other words, fixing MysteryBall is the "target exercise" of part 2 of this assignment, but Gemini/Sibling is available for those who wish to go further.) These files are (hopefully) stylistically better than MysteryBall, but they still lack all documentation. This is for you to fix, of course.
For this part of the assignment, you should turn in the MysteryBall.html (or ballworld.MysteryBall.html) file produced by javadoc from your documentation. If you improved the code, also turn in your MysteryBall.java file and a brief explanation of the changes you made; if you documented GeminiBall/SiblingBall, turn in the javadoc'd html for those files as well.
Part 3: Code Revision
The final portion of this assignment involves actually revising some code. To make this easy, we're asking you to revise your own code, although you are welcome to peer edit to your heart's content. Select one of your completed lab assignments (excluding Etch-A-Sketch) and re-do your code. You may choose to ignore what you've done entirely and simply begin again; however, you will still need to explain how your new code improves upon your old. If you cannot find anything to improve in your existing code, go on to some of the gravy exercises that you did not complete. (If you cannot find anything to improve in your existing code, you are either one of the world's best programmers or not looking hard enough.)
The point of this assignment is style, not functionality (although it should reinforce basic programming skills as well). Be careful to distinguish between the use of fields and local variables; use this when appropriate; make sure your methods are invoked using . syntax; use helper methods; use public, private, and protected as appropriate; etc. Document well. It is fine to use things that you learned after the original lab date to improve the code that you produce.
We expect that you will complete Part 3 of this assignment in lab on Friday, October 10. However, you may use the open lab session on Monday, October 6, with the caveat that not all of the nodenet/calculator problem sets may be returned by then. You may also work on this assignment outside of class, but please do not spend more than six hours total (including lab sessions) on part 2 of this assignment. I expect that it will take most students 4-5 hours.
As always, come to lab prepared: Know what you are going to work on and how. You will probably want to have marked up your old code or created a new development plan. Be realistic in your ambitions. Remember that the goal of this exercise is style, not content.
NOTE: If you will not be doing this problem set in lab on Friday, please let us know ASAP.
For part 3, you will need to turn in your revised, documented code and a (one paragraph to one page) write-up of what you changed, why, and how. Be sure to include a critique of the aspects of your prior code in need of improvement or expansion.
What To Turn In
Your completed assignment should include:- on the front page, how much out-of-class time (approximately) you've spent on reading, on preparation of the homework, in lab, and on other non-class-time course-related activities (and what). These times should include work from Wednesday October 1 at 5pm to Wednesday October 14 at 5pm, i.e., two weeks.
- For Part 1: Independent Study
- your explanatory aid
- a paragraph explaining what you learned from this exercise, citing your source
- For Part 2: Documentation and Code Understanding
- the html file produced by javadoc from your documented code
- the MysteryBall.java file only if you modified the code. Also include a brief explanation of how you changed the code. if you documented GeminiBall/SiblingBall, turn in the javadoc'd html for those files as well
- your revised, documented code
- a (one paragraph to one page) write-up of what you changed, why, and how, including a critique of your prior code
