MP0: Target Mode

Before starting the MP you must complete setting up Android Studio and have either an emulator or real device that you can run Android apps on. If you are struggling with this, please come to office hours for help—or post on the forum in the Android Studio category.

You’ll obtain the MP using GitHub—a very popular site that computer scientists use to share their work. So, first, if you don’t have one already, sign up for a GitHub account. Note that if you sign up with your @illinois.edu email address there are some free goodies thrown in.

Next, use this GitHub Classroom link to create a copy of the repository containing the MP starter code. Once your repository has been created import it into Android Studio following our Git workflow guide.

At this point cool your jets for a minute while Android Studio finishes synchronizing and indexing your new project. Once that’s finished, double-check that everything is ready to go by opening the File menu and choosing Sync Project with Gradle Files.

When you’ve finished Checkpoint 0, the app should display a marker on the map at each target’s position. When the user moves within the proximity threshold of a target and it can claimed without violating the snake rule, the target should turn green. Capturing a target should add a green line between it and the previously captured target—if it exists.

This sounds like a lot to do! But you can enable these features by completing just three helper methods in TargetVisitChecker.java:

When your helper functions are ready, you can use them to make the app do something. The Java file controlling the game/map screen is GameActivity. You need to fill out two functions: setUpMap to place all the target markers initially and updateLocation to react to user movements. As noted in the comments inside those functions, some relevant variables are declared and initialized for you near the top of the file.

Finally, LineCrossDetector, which already correctly determines whether two lines cross, has some checkstyle issues that need to be corrected. See the section on style later in this writeup.

We verify the correctness of your code on each checkpoint with a test suite, a Java file containing code that exercises your code, comparing your results and behavior to what we expect. At first, the only test suite is Checkpoint0Test, though there are a lot of other files to hold other code that supports the tests. Each test suite contains several test functions, each of which tests one aspect of your app. For example, our testVisitTarget function verifies the correctness of your visitTarget function.

You can use the test suites to perform iterative test-driven development. You should adhere to this approach as you work on MP0:

When a test suite fails, try to diagnose the problem by looking at what inputs caused your function’s behavior to diverge from what was expected. If your app produced incorrect results, the error will say what it expected. If your code crashed, the error message will show what problematic operation was attempted and what line of your code directly caused it. Either way, the error message also includes what line of the test suite was reached when the problem was hit. You’re not expected to fully understand the test suites, but reading their code may provide some clues about what’s going on in the case that your submission fails.

In general, the fewer lines of code you write before running a test, the better. This is not just a rule for beginners—experienced programmers spend a lot of time writing tests, in fact probably more than when they were learning. When you are starting out, it is easy to introduce bugs into your code. Bugs are easiest to catch one-by-one, and so the fewer lines of untested code, the more likely you are to identify errors in your logic or implementation.

Since the app is a location-based game, it will be useful for you to understand location coordinates, especially when testing your app on a phone or emulator. Digitizing a position on the Earth turns a location into numbers that computers can manipulate, and is what gave rise to smartphone-based navigation, ride sharing, and is also enabling self-driving cars.

Locations are expressed as latitude-longitude (sometimes called "lat-long" or LatLng) pairs. You’ll often see them written as comma-separated coordinate pairs, longitude first.

Latitude is defined relative to the Earth’s equator and specifies how far north or south you are. Longitude is defined relative to the Prime Meridian and specifies how far east or west you are. One increment of longitude is not the same physical distance as the same increment of latitude. The distance between adjacent meridians (a change of 1 in longitude) is different at different latitudes. At the small scales we’ll be working with, however, the curvature of the Earth can be ignored.

You may find this figure helpful:

There are several kinds of errors you may encounter as you work on the project. Distinguishing between them will help you fix them. Remember: programmers never stop making mistakes. They just get better at fixing them.

Before a program can be run, it must be compiled from your source code into something that can be executed. We’ll talk a bit more about this later in the semester. Problems in this stage are compile errors, indicating that your code has a mistake—often a syntax error—that makes Java unable to understand or permit what you’re trying to do. They’re flagged with red squiggles in the code editor or shown in a window like this:

You can usually double-click the error to jump to the code where Java identified the problem. However, unbalanced curly braces can make Java think the structure of your code is very different than you intended. If you suddenly receive tons of compile errors, look before the start of the problems to see if you have an extra or missing curly brace. This is one of many things that proper indentation helps with.

If compilation succeeds but the program tries to do something impossible or disallowed, that’s a crash—a runtime error. The test output pane marks the crashed test with a red icon and tells you went wrong and what line of code caused the crash. For example:

The first line states the problem, in this case that code tried to access the out-of-bounds index -1 of an array. What follows is called a stack trace. The direct cause of the crash is at the top—in this case the getTargetWithinRange method of TargetVisitChecker—and the rest of the stack trace describes how your code reached this point. Helpfully, the stack trace also includes the line number of the code that crashed. You can click the underlined link to jump right to that line.

The other lines are the chain of function calls that led to the crashing function. In this case, getTargetWithinRange was called by line 214 in Checkpoint0Test’s `invoke function, which was called by an access$200 function attributed to line 170 2, which was called by line 236 of testTargetRange. Usually you want to investigate the first stack trace entry that mentions your code, but finding what the test suite was trying to check when your code crashed may also provide some clues. As you continue to write more complex code, stack traces will frequently lead you from the place where the problem manifested itself to the real cause.

Finally, it’s common for code to cause no crashes but produce incorrect results. When these logic errors are detected, the test output pane marks the failed test with a yellow icon and displays a report similar to one from a crash. However, since your code finished executing but just returned a wrong result, only the test code which found the problem will be on the stack trace. Often the message will specify the expected (correct) value and the actual (your code’s incorrect) value. You can jump to the complaining line of the test suite to get more context and see what call(s) it made to your code.

The course staff is ready and willing to help you! If you need help, please come to office hours early and often, or post on the forum in the category we’ve created for MP0 questions. You should also feel free to help each other, as long as you do not violate the academic integrity requirements.

Like any other computer program, an important part of developing on Android is figuring out what your program is doing by generating debugging output. But there isn’t a console visible on Android devices for our familiar System.out.println to write to.

However, Android has a simple yet powerful logging system. Unlike System.out.println, logging systems allow you to specify multiple log levels indicating the kind of output that you are generating. For example, this allows you to separate debugging output that might only be useful during initial development and a warning message that might indicate a more serious problem or failure. The Android logger also allows you to attach a String tag to each message to separate them when you are debugging or developing. So the final syntax of the call to generate a debugging message, for example, is Log.d(TAG, message), where message is the text to log. This assumes that the Java class you’re working in has a TAG constant defined, which GameActivity does.

Logs are visible in the Logcat pane (near the bottom) of Android Studio. You can type in that pane’s search text box to filter what messages you see. For example, if your app crashed, filtering for FATAL will help you find the crash details.

System.out.println will still technically work on Android; it just produces a log message with a tag of System.out. It does have the advantage of showing up in the test results pane, but you lose the ability to organize the logs by tag.

For more information, see Android’s official logging documentation.

Each Android Activity corresponds to a single screen that the user can interact with. For MP0 you’re only working with GameActivity, but the app contains several that will be implemented or created in later checkpoints. Most apps consist of multiple activities: maybe one for its dashboard, another for a settings screen, and still others for other sections of the app.

There are a few important moments for an activity, especially when it is created and when it is terminated. Android provides functions that can be overridden (implemented) to handle both of these events: onCreate and onDestroy. It is typical for on onCreate method to perform tasks required to make the activity ready for a user to use, such as configuring buttons and other UI elements.

For more information review Android’s official Activity information.

Why does code in your app run? In many cases it’s because new information has been made available, either by the user directly interacting with a control in the app or because another part of the system issuing a status update, like how our location listener service notifies the game activity of the user’s movements. Android components provide ways for an app to register handlers: functions that will be run when various events take place.

Our starter code registers one handler for when the map is ready for setup and another for when the GPS location has changed. Implementing them—making them actually do something—is up to you.

Automated testing is a hugely important part of modern software development. Just like computers are good at running programs, they are also good at running programs to debug other programs. Independently developing a method and the function that tests it allows the two to support each other. The test may find errors in the method, and the method may also identify errors in the test.

Testing simple Java functions is relatively straightforward: we invoke your code with some chosen inputs and compare the output to the known-correct result. Testing Android UIs, however, is more difficult. This semester we will continue using Robolectric to test your app code in a Java environment that simulates Android.

For the first checkpoint we test each of the three helper functions with some simple manually designed test cases, then exhaustive test cases using many randomly generated inputs. Since each test function stops as soon as it detects a problem, we placed the simple cases first so you can use them during iterative development. In particular, some simple cases in testSnakeRule have diagrams that visually show why the expected answer is correct.

We have provided you with a local autograder that you can use to estimate your current grade on your own machine as often as you want. Your Android Studio project contains a run configuration called "Grade" that will run the autograder for the current checkpoint. You can also run the grader by installing our plugin and then pressing the button that looks like the CS 125 shield.

Before your grade your checkpoint you will need to identify yourself by entering your @illinois.edu email address into the email.txt file located in the root project directory. The autograder will not run until you do this. Please make sure to get this right! If you don’t, your results will not be visible on the grading page, and may be attributed to another student—putting you at risk of an academic integrity violation.

Unless you have modified the test suite or autograder configuration, the autograding output should approximate the score that you will earn when you submit. If you modify our test cases or the autograding configuration, all bets are off. You may also lose points if your solution runs too slowly and exceeds the testing timeouts.

First make sure you’ve identified yourself in your repository by entering your Illinois email address into the email.txt file in the outermost folder of the project.

Whenever you make progress you want to save, you should be making a Git commit (VCS | Commit). Commits only exist on your computer until you push them (VCS | Git | Push). Every time you push your MP, we grade the checkpoint you’re currently working on. Official autograding takes just a few minutes, then you’ll be able to see results on the MP grade page.

Most of the points on each checkpoint are for correctly implementing the required functions. The other 10 points are for style. Writing readable code according to a style guideline is extremely important, and we are going to help you get into this habit right from the start. All software development companies and most active open-source projects maintain style guidelines. Adhering to them will help others understand and integrate your contributions.

We have configured the checkstyle plugin to enforce a variant of the Sun coding style. Android Studio should naturally produce formatting that meets this standard. So you shouldn’t have to fight with it too much to avoid checkstyle violations.

For ease of finding style problems, Android Studio flags them with red squiggles under code and with red tick marks on the scrollbar. You can hover your mouse over such indicators to get more details on what checkstyle is complaining about. You will also get a full list of checkstyle errors at the top of the grading output.

You may find these requirements a bit annoying at first, but we trust that you will get used to them. Once you build good style habits, you won’t have to think about them anymore, and will just go on writing beautiful code.

If you can’t wait to see how the app will work when you’re done with the MP, you can set our module manager to use all of our provided libraries. There’s a file called grade.yaml in the root of the project that will be used in later checkpoints to indicate what you’re currently working on, but if you change its checkpoint setting from 0 to demo and its useProvided setting from false to true then do File | Sync Project with Gradle Files, building and running the app will produce our solution. (The Gradle sync step is important! Without that, very strange behavior will occur.) Make sure to change those settings back and Gradle sync again before trying to grade or submit, since you don’t get points for grading our known good solution.