Squee Developer Documentation

These are the latest versions of the documentation, taken directly from CVS:

• Requirements [RTF]
• Design [RTF]
• Design Diagrams [PDF] [VSD]
• Squee Game Rules [RTF]

Using CVS

Using CVS is reasonably easy once you know what you're doing. Here's a step-by-step guide on how to download our source code so you can load it into an Integrated Development Environment (IDE).

1. Download and install a CVS client. We're using TortoiseCVS, but you can use a different client if you're feeling brave. We warn you, however, that we won't be able to help you if you have problems.
2. Next find or create the directory where you want to put the project files. All of TortoiseCVS's functionality can be accessed by right-clicking the mouse in Windows Explorer.
3. Right-click inside your target directory and choose CVS Checkout...
4. The following window pops up. Enter the following into the CVSROOT input box (replace yourname with your sourceforge username):
   
   :ext:yourname@ugene.cvs.sourceforge.net:/cvsroot/ugene
   
   This will fill in almost all of the information required. The only thing missing will be the Module input box. Type in UGENE for the Five Thousand project, or Squee for the Squee project.
   
   
   
   
5. From now on, remember that the CVS commands checkout and update download from the server to your computer, while the commands add and commit upload from your computer to the server.
6. Import the source code into the appropriate development environment. We're using Eclipse for Squee (see Importing Your Project Into Eclipse), and we used CodeWarrior 7.0 for Five Thousand.
7. After you're done programming, all of the files you changed will display in red on Windows Explorer. Save your changes to the CVS server by right-clicking and choosing the commit command.

Eclipse Guide: Finding, Installing and Using

We're using Eclipse to develop Squee. It's a free, cross-platform Integrated Development Environment (IDE) that's the perfect fit for developing an open-source Java game (or anything in Java, really). Once you get used to it it's a breeze to work with and you'll be very productive.

Time-Saving Tip: If you are just getting started and this seems a tad overwhelming for you, just contact Jonathan and he will send you a compressed file containing Eclipse and all of the plugins already installed (it's about 120 MB).

In general, we're using the most up-to-date versions of Java, Eclipse and a set of plugins. Here are the software versions we're using, along with useful information:

• Java J2SE SDK 1.5, Update 7. This project depends on RMI (much improved in Java 1.5) and many other really neat features that have come out in Java 1.5, hence older versions of Java are not good enough. TO INSTALL: Double-click on the installation program.
• Eclipse 3.1.2. The latest and coolest stable version of Eclipse. TO INSTALL: Extract the ZIP file into your C:\Program Files\ folder.
• Jigloo 3.8.2. This is a totally cool graphical editor for Swing. It cuts the time required to create nice GUIs to a fraction of the time it would take to do them manually, and also means that you don't need to know the intimate details of how Swing works--so you can concentrate on learning more important things. TO INSTALL: Download the ZIP file and extract it to C:\Program Files\eclipse\. TO USE: In the Eclipse Package Explorer right-click on a GUI class and select Open With->Form Editor.
• Find Bugs 1.0.0 RC2. This nifty plugin is used to search through your Java code looking for bugs. Unlike the compiler, it looks for more sophisticated and hard-to-find bugs. Unlike the compiler, it's fairly likely to come up with false positives. TO INSTALL: Download and extract the ZIP file to C:\Program Files\eclipse\plugins\ (Note: this is different from the Jigloo plugin). TO USE: In the Eclipse Package Explorer right-click on any class and select Find Bugs->Find Bugs.
• AspectJ Development Tools (AJDT) 1.3.1. AspectJ is an extension to the Java language which enables Aspect-Oriented Programming (AOP), the newest programming paradigm that complements Object-Oriented Programming. It's an essential part of the learning experience that is working on Squee. TO INSTALL: Open Eclipse and click on Help->Software Updates->Find and Install.... Select Search for new features to install. Click on New Remote Site.... Enter the name AJDT and URL http://download.eclipse.org/technology/ajdt/31/update. After installation, restart Eclipse. TO USE: In the Eclipse Package Explorer try right-clicking and selecting New->Other...->Aspect.
• JUnit 4.1. JUnit is library for unit testing Java classes. It's easy to use and well-integrated into Eclipse. You don't need to download it since it's already in our CVS. TO INSTALL: In Eclipse, with the Squee project open, select Project->Properties. On the left choose Java Build Path and then click the button labelled Add External JARs. Select the JUnit JAR file located here: ~\Squee\libraries\junit-4.1.jar, and then accept your changes. TO USE: In the Eclipse Package Explorer right-click where you want to create a new test case, and select New->JUnit Test Case.

Importing Your Project Into Eclipse

Here is a step-by-step guide to importing your project into Eclipse v3.1:

1. In Eclipse, go to File->New->Project
2. Select AspectJ project
3. Name the project (e.g. Squee)
4. Under JDK Compliance, make sure that compliance is with Java 5.0
5. Under Project layout, make sure that Create separate source and output folders is selected
6. Click Finish
7. In Eclipse's Package Explorer, click on the folder src in the Squee project
8. Go to File->Import->File system
9. For From directory:, click Browse...
10. Find and select the directory where you downloaded the source files from CVS (e.g. ~/Squee/source_code, where ~ is the place you downloaded the CVS to)
11. Click OK
12. Click on Select All
13. Click on Filter Types...
14. Check only *.aj and *.java
15. Accept your changes and exit the window.
16. At this point the project should build correctly.

At this point, you may be getting a ton of warnings from the compiler, that look something like this: can not build thisJoinPoint lazily for this advice since it has no suitable guard.... This is a warning that the AspectJ compiler can't optimize a part of the code--in other words, not a big deal. To get rid of these warnings, click on Windows->Preferences->AspectJ->Compiler, and under No guard for lazy tjp, select Ignore.

If you have any problems importing or building the project using Eclipse, please let me know. I'll help you through the problem, and then post any updates or corrections here. One major problem I know of right now is that you should avoid using the Eclipse integrated CVS to download Squee (Skrud tried it and it didn't work).

Hints on Using Eclipse Effectively

When typing in a reference, typing Ctrl-Space gives you code completion options. When highlighting an error or warning, typing Ctrl-1 gives you common solutions to the problems, which are almost always very relevant to the situation.

Code Review Guidelines

The following are guidelines designed to help the team perform effective code reviews.

What Is A Code Review?

A code review is when one or more programmers get together to read over a portion of the project's source code. The goal is to read and understand the code, determine if it is correct (i.e. does what it is supposed to), make note of problems, and fix the problems if necessary.

Be cautious of making changes if one of the original programmers is not present! There may be an unspecified reason why things were done that way... or it may just upset the author.

Who Should Review?

Code reviews should be undertaken by two people, one of whom was the code's original programmer, and one person that had nothing to do with writing it. This way there's somebody to explain what's going on, and somebody with a fresh perspective. Having only one person, or three or more, is likely to be less productive than a pair. In particular, having too many people reviewing is likely to just waste a lot of people's precious time.

What To Look For During A Code Review

Create a checklist of the following elements, and look for each of them in turn.

Effective Comments: It's vitally important that the source code has a sufficient quantity of effective comments. We're a team here, and thus many people other than the original author(s) need to understand what's going on. Effective comments are comments that are useful, and actually help the reader to understand, and possibly modify, the code.

• Every class should have a comment header that gives a general description of the class, what it does, and anything special about it (e.g. features, limitations) that people should know about. These comments are necessary for the user of the class.
• Every class needs an example of how to create it, use it, and (if necessary) destroy it. This means actual commented out source code, preferably code that has been tested to see if it compiles.
• If the class throws exceptions, then the comments should document which exceptions the class throws, as well as the reasons why particular exceptions are thrown. It would also be nice to mention if the exceptions are fatal, or can be recovered from (and how to recover).
• Every class needs a change log, that documents who made what change(s), and when.
• Within the class header file, every non-trivial function and attribute needs a short description of what it does, and any caveats.
• Within the class source file, comments should aim at adding information so that the reader can better understand what's going on. Hence, comments should generally be at a higher level of abstraction than the code itself. Comments that simply repeat the code are not only useless, but dangerous, because they can easily become out of synch and confusing.

Data Checking: One of the most important goals of code review is in figuring out how user input could mangle the program during runtime, and then seeing if the authors anticipated this problem. It's important that the class's functions check data they receive from the user before they apply it. For example, if a function expects input variable theta, a float between 0.0 and 359.9, then make sure that either the function throws an exception when it gets data not within that range, or it corrects the data. Which technique is used depends on the situation--but make sure that you document your choice.

Exception Handling: Check that wherever runtime errors might occur, either exceptions are being thrown, or error correction techniques are being applied (as described under Data Checking). Make sure that exceptions are recoverable whenever possible, and fatal (i.e. result in the program ending) only when necessary. Finally, ensure that the function in question cleans up after itself before the exception is thrown. For starters, this means that any invocation of the new command inside the function's scope must be matched by a delete before throwing.

Class Design: See if you can't think of a better way to design the class. Perhaps one of its attributes is unnecessary, or there's a clearer way to organize its functions? Important design patterns to apply here are Information Expert (the class should be the repository for its own data), and High Cohesion (try to keep the class's purpose as simple as possible).

Coding Convention: It's a good idea to make sure that the coding convention is being followed (e.g. good variable names, classes written in all caps, etc.). Ideally, the author(s) should already have taken care of this, since the whole point of using the convention in the first place is to make code review easier.