Homework 1.  CS4240 Principles of SW Design

Last modified: Sept. 2, 2010, 3:30 pm

Summary:  Explore an existing SW application to learn about the structure of its design.  Also identify any code smells or other design flaws that you discover.  Document the results.

Learning objectives for this homework:
When Due:  Weds., Sept. 15, 11:30pm.  Submit this to the ITC Collab site for the course.  Late: 10% penalty per day, up to two days late.

Group project?  You may work in pairs but each person must understand all aspects of the solution.  Teach each other; don't simply divide and conquer.

What to do:

1) Choose one of the SW applications available for this assignment.  Each has been stored so that it can be unzipped and then imported as a project into Eclipse.  (You can use another IDE to explore this code, but we'll assume you're using Eclipse since it has some nice features for working with large projects with many files.)  If you have some other application you want to use, that's possible -- contact me.

2) High-level Structure:
Examine the code and see if you can identify any organization at a higher level than the class level.  If the code is divided into packages, see if you can describe each package in terms of its purpose and what it contains.  Don't just list the classes in it; try to understand the package as a subsystem or a organizing-unit at a higher-level of abstraction than a set of classes.  If you see things inside the package that seem out of place, note those.  If there is not a good package structure, see if you can identify some relationships among the classes that gives some kind of logical organization to the system. (For this part, don't look at inheritance relationships. See next item.)

3) Inheritance Relationships:
Find and document inheritance hierarchies in the code.  (If there are a lot of these, identify two important ones and just document those.)  For the documentation, write a short paragraph describing each hierarchy's purpose and role in the system, and what abstractions it tries to capture in its superclass(es).  Comment on any problems you see in this use of inheritance, if any are obvious. Also, draw a UML class diagram of each hierarchy you document using the Violet UML tool. (Or anything else, but Violet is easiest. Later we'll use a more professional UML tool, and if you want to start with that and not use Violet, ask me for details.  Keep this diagram very simple by not including any fields or methods (though you can if you want).
(Link to the Violet tool.)

4) Code Smells:
Try to sniff out at least three different code smells or other low-level design or coding problems in this system.  Don't simply look for the bad coding problems (e.g. bad comments, bad names, bad formatting, etc.) but instead look for design-level issues as discussed in class. If you find problems, suggest solutions.  (You don't have to change anything or turn in better code.)  Write up what you've found, and cut-and-paste code from the SW app to show what you've found.
Note: If the system you have seems to be of high quality and doesn't have code smells, then choose at least three examples of methods or classes that you think do exhibit good software design properties.  Explain why.  If you choose a method, you must pick some of the larger or more complex methods in the code.  (No points for explaining why a getter method is well designed!)
Links: Here's a link on Code Smells -- look for some of these related to design.
Better info on Code Smells is found in Robert Martin's book Clean Code in Chapter 17.  See the link on the Resources page of the class website.

5) Design Report:
Document the results of 2, 3 and 4 above in a Word or PDF document that I can read.  At the top, state what system you're reviewing and the names of your team members.  Turn this in using the submission system by the deadline.  In this document, you do not have to write long reports or wordy descriptions as long as you cover the points above. Imagine you are writing for your manager who needs to understand clearly but is also very busy.

6) Part 2:  JUnit and Ant
We will ask you to create some JUnit tests for the system you study (or one of the others), and also to learn the basics of the Ant build tool.  Each person will do this part on their own.  We are working on the details (Ant tutorials, directions for what to do, how to demonstrate this works, etc) and will let you know as soon as we've worked it out.  (Part 2 may have a different due date.  It's worth no more than 30% of the total assignment, perhaps less.  Stay tuned.)

Systems:  Other software systems may be added to this list.  If you want to suggest or contribute, one let me know!
The following should (I think) be "importable" into Eclipse by clicking Import on the File menu (or right-click the Package Explorer).
  1. eeclone: a simple game where you blow things up!
    Download Zip file from the Files page.
    Run it using EEClonePanel.main()
    More info on this app is here.
  2. RealEstate: a Monopoly-like game
    Download Zip file from the Files page
    Run it using Main.main() in package edu.ncsu.realestate.gui.
  3. Tyrant: is a graphical "rogue-like" fantasy adventure game.
    Download Zip file from the Files page.
    Run it using QuestApplication.main() in package mikera.tyrant  (Yikes! Currently fails as of Sept. 2.  Stay tuned.)