Project 1, part 0: Setup

Overview

This section of the document explains how to set up and configure your development environment.

You do not need to submit anything for part 0 and there is no due date, but we strongly recommend you work through this section as soon as possible. Part 0 contains instructions and mini-exercises designed to make sure you're comfortable with your development environment which you'll be using throughout the quarter.

If you run into any issues or have questions about any of these steps, you should ask one of the course staff as soon as possible so you don't run into issues down the line.

Part 0a: Installing your IDE

First, start by setting up your development environment if you haven't already. We STRONGLY recommend you install and use an industrial-strength integrated development environment (IDE) instead of using jGRASP. The two IDEs we official support are IntelliJ and Eclipse: here are instructions for installing and using both.

Part 0b: Visit Gitlab and clone your repository

You should have recieved an invite to our internal Gitlab server. Go to https://gitlab.cs.washington.edu and log in using using your UW NetID.

Add instructions here

If you are unable to get any of these steps working, talk to the course instructor ASAP.

Part 0c: Run tests locally

Once you have finished setting up your IDE and your project, try running the tests we have provided you.

You can do this by right-clicking on the test and selecting the "run" option. You can find instructions and screenshots on how exactly to do this in your "installation and usage" for IntelliJ or Eclipse.

When you try running your tests, your IDE should print out the names of each test, state that they failed, and include some sort of error message and stack trace under each one.

If you are unable to get your tests running, talk to one of the course staff ASAP to get help.

Part 0d: Commit, push, and pull changes

Your "installation and usage" guides for IntelliJ or Eclipse (linked above) should include instructions on how to commit, push, and pull changes using version control. We will now practice following these instructions.

  1. Have partner A make a minor change like adding a comment to your DoubleLinkedList class. Commit then push this change.

  2. Have partner B pull then open the DoubleLinkedList class. You should see the change partner A made!

  3. Switch places and repeat these steps so partner A can practice pulling a change partner B made.

Next, we'll practice resolving merge conflicts: handling cases where both partners ended up changing the same thing in different ways.

  1. Have both partners make a change in the exact same location: for example, try adding a comment to the very top of the file. Make sure your comment is different from your partner's!

  2. Next, have both partners commit and push their change. Have partner A push first, followed by partner B.

    Since partner A went first, their push should succeed. However, since partner B went second, they'll get an error message complaining about a merge conflict: Git wasn't sure how to combine your commit with partner A's.

    If you look at your DoubleLinkedList class again, you should see Git edited that file so it contains both alternative. It should look something like this:

    TODO: example here

  3. Partner B now needs to edit the file and combine both changes. You can do this however you like: keep your change, keep your partner's change, combine them together somehow, replace the changes with something completely new, delete both...

    Ultimately, all that matters is you somehow edit the file so it compiles again. Once you're done, commit and push.

  4. Partner A should now pull: they should now see the merged change partner B made.

  5. Switch places and repeat these steps so partner A can practice fixing a merge conflict.

Make sure both partners try pulling once you're done to make sure you're both in sync.

Part 0e: Continuous integration and style

In this course, we will not grade your code for style issues by hand, like we did in CSE 142 and 143. Instead, we'll run your code against style linters — tools that automatically check your code for various style issues.

You can see the output of these tools by logging into Gitlab, going to your project, then clicking TODO: figure out what buttons to press.

If you read through this page, you should see two things: the linters complaining about various style issues, and the output of your unit tests (which should currently all be failing).

Both the linters and your unit tests will be re-run every time you push a change.

Note: you are not guaranteed to get full points on this assignment even if none of the linters complain and all of your unit tests are passing. You may still lose points if:

  1. You submit truly disgusting and unreadable code that somehow passes the style checkers.
  2. Your code does not pass our private unit tests. (The tests we've given you are deliberately incomplete).
  3. If your code made poor design decisions

Design decisions are higher-level decisions you made on how to implement your code. Here are some examples of what poor design decisions look like:

  1. Your code does not follow the restrictions listed in this spec.
  2. Your code is not asymptotically efficient.
  3. Your code contains gross redundancy.

Note: We will cover what exactly it means for code to be asymptotically efficient a little later this quarter. For now, we'll use a simpler definition: a method is asymptotically efficient if it uses as few loops as possible.

Testing and code reviews in industry

Companies in industry spend a lot of time and energy making sure their code remains bug-free. While many bugs are harmless, many other bugs can be extremely embarassing or even fatal to companies. For example, bugs can cause loss of customer trust, privacy leaks, catastrophic data loss, financial loss, or even loss of human lives.

To help detect these bugs, companies rely on a mix of automatic and manual testing.

One strategy is unit testing: developers will write tests for each individual "unit" of code and automatically run these tests any time somebody tries submitting a change to catch regressions – newly introduced bugs.

Another strategy is to run static analysis tools against their code. Some static analysis tools will do extremely sophisticated checks; others will only check for style issues. Tools that check mainly style are called linters.

Yet another strategy is to do manual code reviews: to have another human do a final sanity check over a proposed change.

We've attempted to set up our projects so you get exposure to as many of these strategies as possible.

Part 0d: Exploration

Finally, explore the rest of your project with your partner and become comfortable with where everything is located. You do not need to understand all of the code provided to you, but you should at least be aware of where the files you need to modify are located.

We've included some extra info below to help you with your exploration process. (Remember, click the box titles to expand).

Project overview

When you open your IDE for the first time, you will see many different folders and files. Most of these are configuration files for your IDE: you can safely ignore most of them. The only folders you need to pay attention to are the src folder and the writeups folder.

Here is a high-level overview of what the src folder will contain:

  • src
    • main
      • antlr — Contains a grammar describing the mini-language you will be implementing. You should ignore this folder.
      • java
        • calculator — Contains code related to the calculator language and the GUI. You will modify some of these files.

        • datastructures — Contains abstract classes and (empty) concrete implementations for the data structures you will be implementing in this assignment.

          Notice that we have prefixed each interface with the capital letter "I". This is not standard Java convention – we use this prefix so we can easily distinguish our our interfaces from the ones in java.util.

        • misc — Contains miscellaneous utilities and files. You may not use or modify any files within this package unless instructed to.
    • test
      • java — Contains tests for your project. We have provided some tests for you; you will be required to add some extra tests as a part of this project.

Java packages

In Java, the main way we organize projects containing multiple files is by using packages.

The most important things you need to know are that:

  1. To declare a Java file is a part of a package, you must include the line package some.package.name; at the top of the Java file.

  2. By convention, we store files in folders matching the structure of the package name.

    For example, one of the files in our project is located at src/main/java/datastructures/concrete/DoubleLinkedList.java. We've configured this project so src/main/java is considered the "root directory" of your Java source code. That means that DoubleLinkedList.java will be located inside the datastructures.concrete package.

    There will always be a one-to-one mapping between the package name and the folder it's in.

  3. To import a class from a different package, include the line import some.package.name.SomeClass; at the top of the file. You do not need to import any classes that a part of the same package as the current class.

You can find more details about Java packages at this link.