Contact Us      Site Map      Search
Home Documentation Developer

Page Contents

Squee Developer Documentation

Using CVS

Eclipse Guide: Finding, Installing and Using

Importing Your Project Into Eclipse

Hints on Using Eclipse Effectively

Code Review Guidelines

Squee Developer Documentation

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

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

    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.

    Tortoise CVS Checkout

  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:

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.

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.