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.
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:
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.
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.
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.
We plan on grading your code for style by:
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:
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.
At this stage, everything should be installed and configured. To confirm everything is ok, do the following:
SanityCheck.java. This file is located at
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.
Run a test. For example, try right-clicking
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.
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:
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
SanityCheck.java class should have exactly the above
If you are unable to get any of these four steps working, please talk to the course staff ASAP.
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).
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
Here is a high-level overview of what the
folder will contain:
experimentdata — a folder that will eventually contain
some experimental data you will be asked to generate for your writeup.
Contains a grammar describing the mini-language
you will be implementing. You should ignore this folder.
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
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
misc — Contains miscellaneous
utilities and files.
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.
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.
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:
To declare a Java file is a part of a package, you must
include the line
at the top of the Java file.
By convention, we store files in folders matching the structure of the package name.
For example, one of the files in our project is
We've configured this project so
is considered the "root directory" of your Java source
code. That means that
will be located inside the
There will always be a one-to-one mapping between the package name and the folder it's in.
To import a class from a different package, include
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
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.