CSE 373, Winter 2018: Project 1: Part 0

Overview

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

While there are no deliverables in this part of the assignment, we strongly recommend you complete them as soon as possible so you have plenty of time to visit office hours if you run into issues.

If you run into any issues while following these instructions, or just have any general questions on using Eclipse, please talk to a member of course staff ASAP during office hours.

Part 0a: Install your IDE

First, start by setting up your development environment if you haven't already. You may NOT use JGrasp – you MUST use a full-fledged integrated development environment (IDE). We recommend using Eclipse – installation and usage instructions can be found on the resources tab.

Here are direct links to the guides you should read:

  1. Eclipse: Installation and setup guide
  2. Eclipse: Project import guide
  3. Eclipse: Basic usage and overview

If you have Eclipse installed already, please read through the installation guide anyways: you need to install a plugin and change a few of Eclipse's default settings.

Please also make sure you are using the latest version of Eclipse, which, as of time-of-writing, is Eclipse Oxygen. If you are not sure what version of Eclipse you're running, think back to when you installed it. If you installed Eclipse sometime within the past 6 months, you're probably ok. Otherwise, you should probably uninstall and re-install Eclipse just to be safe.

Part 0b: Download your project

Download and unzip the project files.

Extract it and open it in your IDE – see the project import guide (linked above) for more details.

Note that since you should be pair-programming with your partner in person, technically only one partner needs to download the project.

If you and your partner wish to collaborate remotely, you will probably want to use a version control system such as Git to help manage your code. (Git is a tool used almost ubiquitously in industry to help people keep track of changes they make to their code and collaborate with their teammates in a principled way.)

Using Git is entirely optional within this class (though we do encourage you to try learning how to use it). We will post detailed tutorials on using Git at a later date if you are interested in using it for either this project or subsequent ones.

If you already know how to use Git, you must store your code in a private repository – we want to re-use these projects in future quarters and don't want solutions available online.

You can get unlimited private repositories if you use Bitbucket or if you use Github (if you apply for the student developer pack).

Part 0c: Get style feedback

In this course, style will be graded 100% automatically using tools known as style linters. Style linters are not perfect and are no substitute for manual code reviews, but they do a pretty good job of catching many common issues and so are used very frequently in industry.

When you were following the above instructions on how to install Eclipse, you should have also installed the checkstyle plugin and configured it with a set of rules downloaded from the course website.

If you are using a different IDE, here is a direct link to the checkstyle configuration file you must use.

After you finish, you can run checkstyle on your computer to perform the exact same set of style checks we will be using to grade your code. If you run checkstyle and it reports no issues, you will get full points for style.

How will style be graded, exactly?

We plan on grading your code for style by:

  1. Running the same linting tools the submitter tool uses.
  2. Briefly performing a manual sanity check over your code to make sure it's more or less readable and you didn't somehow fool the linters.

Since we're giving you the same linting tools we'll use to grade your code, everybody should be able to easily get full points for style.

Note: we will, however, grade the design decisions your group made by hand. Design decisions are the higher-level choices you made while implementing your code. Examples of poor design decisions include:

  1. Not following restrictions listed in the spec.
  2. Implementing asymptotically inefficient code.
  3. Writing grossly redundant code.
  4. Having your data structures use an excessive and unnecessary amount of memory.
  5. Structuring your code in an excessively awkward way.

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.

This metric is a really bad way to measure efficiency, but it's good enough for now.

Part 0d: Running sanity checks

At this stage, everything should be installed and configured. To confirm everything is ok, do the following:

  1. Run SanityCheck.java. This file is located at src/main/java/misc/sanity/SanityCheck.java: right click the file from the project explorer and select the option to run it.

    Important note: you should be running this file from within Eclipse. In the pane to the left, navigate to the file, right click it, and select the "Run" option.

    If Eclipse asks you if you want to run this as a Java application or a Gradle task, pick the Java application option.

    If everything went well, this file should successfully run and print out a few lines of output.

  2. Run a test. For example, try right-clicking src/test/java/datastructures/TestDoubleLinkedList.java and select the "run" option.

    As before, you should be doing this within Eclipse. If Eclipse asks you if you want to run this as a JUnit test or a Gradle task, pick the JUnit test option.

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

  3. Try running checkstyle on your entire project. See the Eclipse usage guide for details on how to do this.

    Checkstyle should report exactly five errors with SanityCheck.java:

    1. Line 7: Unused import - datastructures.concrete.DoubleLinkedList.
    2. Line 19: Found a stray TODO/FIXME comment.
    3. Line 20: Declaring variables, return values or parameters of type 'ArrayList' is not allowed.
    4. Line 21: Line is longer then 120 characters (found 149).
    5. Line 22: '(' is followed by whitespace.

    You can find these errors listed in the Checkstyle view (the Eclipse usage guide will instruct you on how to open this view). These lines should also be highlighted in red within your editor window: you can hover over them to see what the error is.

    And finally, Checkstyle will add a little red "x" icon next to any file that has style violations in your Package Explorer view. (Eclipse will also flag any files that won't compile with the same red "x" icon).

    If checkstyle is not reporting any errors, or is reporting far more then these five errors, something has gone wrong. (Note: you may either fix these errors or ignore them. We will ignore SanityCheck.java when grading your code for style.)

    (Note: Checkstyle should also report several other "Found a stray TODO/FIXME comment" located in different files throughout your code. This is expected – those TODOs mark code you'll eventually need to edit. However, if we ignore those errors, the SanityCheck.java class should have exactly the above 5 errors.)

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

Part 0e: 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:

  • experimentdata — a folder that will eventually contain some experimental data you will be asked to generate for your writeup.
  • src
    • main
      • antlr — Contains a grammar describing the mini-language you will be implementing. You should ignore this folder.
      • java
        • analysis — Contains code you will use to collect data for your writeup.
        • 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 interfaces from the ones in java.util.

        • misc — Contains miscellaneous utilities and files.
    • 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.
    • writeup The folder where you will store your writeup and associated files.

If you're curious, this method of structuring our files is heavily inspired by the Maven directory layout standard. It's a fairly popular way of organizing large Java projects, so it's good to get some exposure to it.

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.

    If you try and use a class that was not previously imported, Eclipse will often automatically add a line importing that class for you. While this is convenient, it can also be a little messy: if you start using a class then later change your mind, the (now unused) import line Eclipse added will stay in your file.

    You should go through and check your imports from time to time to remove any unused ones: the checkstyle plugin should help you do this.

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