Informatics 122: Software Design II Project #2

Introduction

The previous project focused on learning about how to communicate the details of a software design to others, then gave you a chance to share your design with others and receive feedback on it. For some of you, this may have been the first time you've had peers review your work in a lower-risk way than when you've been graded by TAs and instructors. It may also have been the first time you've been confronted head-on by the experience of watching someone else respond to your work right in front of you. If you're accustomed to being insulated in your own world, working on projects in the safety of your own mind, it can be jarring to get this kind of feedback, especially in-person, but it can also be hugely instructive, because it's sometimes hard to see around your own biases.

A big focus in writing up and diagramming your design in the previous project was finding an understandable way to communicate its details, and your peer reviews should have given you an early indication of how well you did. Each of you has probably found ways you could improve the next time, and that's why you're here.

It's important to note that this isn't just a classroom technique. This kind of interpersonal feedback process is actually quite common in the software industry and in open source projects, where design reviews and code reviews are done at many different stages of the design and implementation of real software. It is critical that you develop your skills at communicating technical details with others, with offering feedback tactfully but technically, and with accepting well-intentioned feedback without taking it personally.

In the end, you were asked in the previous project to evaluate designs belonging to three other students, and to write up your findings. We also asked you to rank-order the three designs, ultimately forcing you to choose a favorite. This project asks you to own that decision, by requiring you to implement the design of the three that you thought was the best. It will also ask you to reflect on your decision after the fact, and consider whether you believe that you made the right one; once you have to live with your favorite design for a while, do you still think it will be your favorite?

Implementing a design in Java

One of the key takeaways from your peer design reviews was a decision about which of the three other students' designs you thought, given all the various factors you considered, was the most implementable. You ranked the design 1st, 2nd, and 3rd. Now we'd like you to put your "money where your mouth is," so to speak, by implementing the design that you ranked above the others. To be clear, we are specifically disallowing you from implementing your own design; instead, you'll be implementing the design that you ranked 1st.

Your goal here is to implement your favorite of the other students' designs in Java. You must implement it as faithfully as possible, even if you think another approach is better than the one the other student chose. The only changes you are permitted to make to the designs are when the design simply cannot be implemented as specified and still meet the requirements. In these cases, you will be required to justify that decision in writing, and we will exercise some scrutiny during the grading process over whether we think that your decisions were correct.

Of course, to make this part of the project interesting, your end result will be a complete program with a primitive console-mode user interface. Think of it as a test harness that will allow you to exercise your engine. To save you a significant amount of time, that user interface is being provided for you.

• Project #2 user interface

What you'll need to do is hook the design you've implemented into the user interface, so that the whole program runs; though I can't rely on the details of the design you'll be implementing (since everyone is potentially implementing a different one), I've left "seams" in the user interface that will allow you to integrate your chosen design with it.

Rather than provide an exhaustive list of details of what you'll need to do, I've left comments containing the word Inf122TBD in strategically-located places in the user interface where you'll have integration work to do. The provided code is on the order of fifty Java classes in six packages, but you'll find that it's not nearly as overwhelming as it sounds; most of the classes are short, and many of them you'll never have to look at in detail. (One of the skills you need to begin developing, if you haven't already, is the ability to take someone else's code and understand enough about its design and implementation that you can integrate it with code of yours. This project might be your foray into that.)

User interface commands

The complete program is to be a console-mode user interface that supports the following set of commands:

TAKE <takePct>

RACE <race#> <horse#> [<horse#> ...]

POST <race#>

RESULTS <race#> <firstHorse#> <secondHorse#> <thirdHorse#>

WIN <race#> <amountPerHorse> <horse#> [<horse#> ...]

CLAIM <ticketID>

CANCEL <ticketID>

POOL <betType> <race>

Using Git as your version control system

One of the requirements in this part is that you use Git — or EGit, if you're using Eclipse, which is a plug-in that provides the same functionality that Git does, but in a graphical form that integrates nicely with Eclipse's user interface — while you work through your implementation. For all of the reasons we talked about in lecture, version control is a hugely important part of the development process, with Git being a great example of a modern tool for development of all shapes and sizes (small, individual projects like this, all the way up to large, geographically-distributed team-based development). Especially if you haven't used version control before, this is a great chance to become accustomed to it in a relatively forgiving environment.

Rather than submitting your code to us, you'll be submitting a Git repository (i.e., a .git directory) to us, along with your entire commit history from the time you started your implementation — warts and all! While we aren't planning to look through your commit histories with a fine tooth comb, we do expect to see that you were using Git throughout your implementation process. We'd expect to see many commits that are relatively granular and have (at least) brief comments on them; comments should focus not just on what is being committed, but the more important issue of why. We imagine that there will be things you tried that worked out and things that didn't, and that's fine; nobody writes code exactly the way they want it the first time. You may feel that you're having your creative process exposed this way, and perhaps that makes you feel uncomfortable, but this is exactly what happens in most professional and open source projects: there's a source code repository and everything is in it, for better or worse, as even mistakes and regrettable decisions are things that everyone can learn from.

Part of your score on this project is the completeness of the repository. The best way to address this is to embrace Git and use it along the way; almost any attempt to "fake it" after you're already done, or by committing code haphazardly once in a while to make it "look good" is going to be quite obvious when we look at your repository, and you can expect to lose some credit on this project in such a case.

Post-mortem documentation

Along with a Git repository, we'll also be asking you to submit a post-mortem document that details some things about your experience. Focus on these issues:

• What design changes were you forced to make during your implementation? For each design change you made, explain what you changed, as well as why you had no choice but to change it in order to meet the requirements. (It's fine if some of those changes are to accommodate the integration of your design into the user interface; it's not entirely uncommon for designs to be adjusted when it comes time to integrate them with others, especially when the two designs were arrived at independently like these.) No change is too big or too small to include here, though you would obviously have to say less about quick and dirty changes (e.g., a missing field in a class) than you would about something more radical.
• After having completed your implementation, take a fresh look at the two designs you reviewed in Project #1 but did not choose as your favorite. Do you still agree with your own decision? If so, what factors about the other design make you feel this way? If not, what have you learned about the designs that make you believe that you were wrong?

Using EGit with Eclipse

Installing EGit in Eclipse

You can feel free to use the command-line Git tool if you prefer, but for those of you who will be most comfortable using Eclipse, it will make a lot more sense for you to use EGit instead. The following instructions will explain how to get the EGit plug-in installed into your Eclipse installation. (This turns out to be a little bit tricky — it took me a handful of tries to get it right, mainly because different versions of EGit are sensitive about which versions of Eclipse they're compatible with — so I wanted to be sure that you didn't have to waste too much time on it.)

First of all, I'll assume that you're using Eclipse Classic 4.2.1. Feel free to use another installation, if you prefer, but you'll be on your own as far as getting EGit working.

Follow these steps to get EGit installed into Eclipse Classic 4.2.1.

• From the Help menu, select Install New Software..., which will bring up a dialog titled Available Software.
• In the Available Software dialog, in the Work with: field, type http://download.eclipse.org/egit/updates.
• The large-sized list should populate with a couple of choices about kinds of plug-ins you might like to install. Expand the section titled Eclipse Git Team Provider, then check the checkbox next to Eclipse EGit; expand the section titled JGit, then check the checkbox next to Eclipse JGit.
  • Note: EGit is the plug-in that integrates Git-style functionality into the Eclipse user interface. JGit is a pure Java implementation of the Git protocol, which is the product that actually manipulates your repositories. EGit depends on JGit in order to work, so you need both. From a design perspective, it makes a lot of sense for these to be separate: JGit is the "engine" on top of which lots of tools can be built, such as integration into IDEs like Eclipse or NetBeans, stand-alone graphical tools, analysis tools, and so on.
• Click the Next > button near the bottom of the dialog.
• You'll then be shown Install Details, which list version 2.2.0.201212191850-r of both Eclipse EGit and Eclipse JGit. Click Next > to indicate that you really want to install them.
• Next, you'll be asked to accept a license agreement. Feel free to read through it if you'd like, then click the I accept the terms of the license agreement radio button and click Finish.
• EGit and JGit will be installed. You'll then be asked to restart Eclipse for the changes to take effect. Click Restart Now. When Eclipse comes back up, EGit will be ready for your use.
  • Note that Eclipse plug-ins like EGit modify your Eclipse installation, not your workspace, so EGit will be available to you in every workspace you use until you uninstall it.

Getting started with EGit

One of the things I noticed about EGit is that its documentation — at least the documentation I was easily able to find — is not quite up to date. For example, there is an "EGit User Guide," but its screenshots and advice do not appear to match the current version. For that reason, I'm providing a quick primer here on getting started with EGit. I'll leave some details for you to figure out — because that's one of the things you face whenever you use new tools, and I don't want to take that experience from you — but I'd at least like to be sure you get off on the right foot.

First of all, it's important to understand that, underneath the covers, EGit is doing all the same things that the command-line version of Git does. There are still commits with hashes associated with them, changes can still be staged (and unstaged), branches and merges are supported, you can place tags on individual commits, and so on. The only difference is that the commands you might normally type from a command prompt are inside being executed via the user interface. So the things you may have read already in Pro Git still apply here. And when you occasionally find that you want to do something more esoteric that isn't supported in EGit, you can always drop back to using the command-line tool instead.

Follow these steps to create a new Git repository using EGit, set up an Eclipse project to use that repository, and commit the empty Eclipse project into it.

• Start up Eclipse, opening it into any workspace you'd like to use.
• Create a new Java project like you normally would (i.e., right-click in Package Explorer, select New and then Java Project). Be sure that you choose the setting that maintains a separate directory for bin and src, so you can easily exclude the compiled versions of your code (i.e., the .class files) from your source control repository.
• Now it's time to set up this project to use source control. Right-click the project in Package Explorer, select Team and then Share Project....
• The Share Project dialog will be displayed, which will ask you for a repository type. Choose Git (not CVS or others that you see displayed!) and click Next >.
  • At this stage, especially if you're running Windows, you may see a warning about setting up a HOME environment variable. Unless you're very specific about where you want your default Git configuration to be stored, this warning can safely be ignored.
• The Configure Git Repository dialog will now be displayed.
  • Leave the Use or create repository in parent folder of project unchecked
  • Next to the Repository field, click the Create... button.
  • You will now see a Create a Git Repository dialog.
    • Choose a parent directory (i.e., a directory where the Git repository will reside), which can be anywhere except within your Eclipse workspace directory.
    • Give your repository a name.
    • Click Finish.
  • Now that you've created a Git repository, click Finish in the Configure Git Repository dialog.
• Now your project is configured and ready to use EGit and it's been associated with a repository. The next step is to do some housekeeping chores so you can easily control what gets stored in the repository and what doesn't.
  • At the top of Package Explorer is a toolbar with a few buttons on it, one of which is a small triangle pointing downward. Click that triangle, which will reveal a pop-up menu. On that menu, select Filters....
  • A dialog will pop up. Uncheck the checkbox next to .* resources and click OK. This will make hidden files like .classpath and .project visible, so you can store them in your Git repository.
• Now you'll want to create a .gitignore file, to ensure that the bin directory, where your compiled .class files reside, will not be included in your source control repository.
  • Right-click on your project in Package Explorer. Select New, then Untitled Text File.
  • In the editor, type /bin/ (note the two slashes) and save the file.
  • A Save As dialog wlil pop up. Select the project (not any of the folders within it), set the File name field to .gitignore, and click OK.
• Now we're ready to make our first commit, where we commit our empty Eclipse project into our repository.
  • Right-click on your project in Package Explorer. Select Team, then Add to Index. This is equivalent to the Git command git add ., which stages any changed files and makes them ready for commit.
  • Right-click on your project in Package Explorer. Select Team, then Commit.
  • A dialog will pop up showing you what you'll be committing. Ensure that the files are really the ones you want to commit — in this case, they will be — write a commit message, and click Commit.
• You'll now see that the files in Package Explorer have a little yellow "repository" symbol on top of their icons, indicating that they have been stored in the repository and haven't changed since. (If you look more closely, you may notice that the src folder still has a little question mark instead; that's because there are no files in that directory, so it hasn't been committed to the repository yet.)

If you've gotten this far, you're good to go! From here, feel free to check out the EGit User Guide, which, while somewhat out of date, will give you a reasonably good overview of what kinds of things you can do with it.

Deliverables

You will submit three deliverables to satisfy this part of the assignment, both of which are due on Wednesday, February 6, at 11:59pm.

• A zip file containing only a Git repository (i.e., a .git directory). In that repository should be (at least) a master branch that points to the commit that you consider complete (i.e., the code that you want us to grade), along with your entire commit history from the time you started your implementation. Ideally, point the HEAD of your repository to the master branch before submitting.
  • If you used Eclipse and EGit, the Git repository would ideally include your Eclipse project (e.g., the .project and .classpath files in the project directory), but not your entire workspace. If you follow the steps in the section titled Getting started with EGit above, your repository should contain just the right stuff.
• A zip file containing all of the Java source code that comprises your implemented design, along with all of the code we provided to you, arranged into a directory structure that mirrors the package hierarchy. Please include only the .java files here — your src directory, if you're using Eclipse. We'll use this for our own reference, in case we have issues with your Git repository.
• Your post-mortem document. This document can be in either Microsoft Word (.doc or .docx) or PDF (.pdf) format.