CS222 Advanced Programming: Projects

Contents

• Two-Week Project
• Final Project

Two-Week Project

Summary

In this project, you and a partner will work together to create an application that pulls live data from Wikipedia. You will practice all of the techniques we have studied in the first few weeks of the semester while learning some new ones along the way. This will help you better understand course concepts and prepare you for the final project.

Requirements

Your fictional client for this project is Orwellian News Service, whose journalists are currently investigating global politics and propaganda. They are trying to understand the behaviors of Wikipedia editors.

Functional Requirements

The functional requirements for the project are given by the following user stories and their conditions of satisfaction:

1. As an investigative journalist, I want to see who most recently changed a Wikipedia article so that I can include that information in my article.

   • When I enter the name of a Wikipedia page, the application shows me the username of the last account to change that page.
   • Let me know if there is no such Wikipedia page for the search term.
   • Notify me if there is a network error that prevents current access to Wikipedia.

2. As an investigative journalist, I want to know if a Wikipedia page’s canonical name is different from my search term.

   • The application clearly shows when a redirection has occurred. For example, a search for “USA” redirects to “United States,” so if I search for the former, I can see that I have been redirected to the latter.

3. As an investigative journalist, I want to know about the last thirty changes to a Wikipedia page so that I can determine whether I need to investigate anything suspicious.

   • The system responds with the username and timestamp of the most recent thirty edits.
   • Times are given in ISO 8601 format in UTC.
   • If there are fewer than thirty changes in the history of the page, show all the changes.
   • Notify me of network errors or failed searches as above.

Nonfunctional Requirements

1. Each solution will be completed by a pair of students in the same section. If there is an odd number of people in a section, we may have one group of three.
2. Your solution will have its own private repository on GitHub within our GitHub organization. Name the repository in the format twp_user1_user2, where user1 and user2 are the BSU usernames or surnames of the team members. Keep the repository names entirely lowercase.
3. Each team will follow the rules of code quality studied so far this semester. This includes abiding by the Single Responsibility Principle, using model-view separation, and developing the domain model using Test-Driven Development.
4. Follow the FIRST principles: unit test are Fast, Isolated, Repeatable, Self-Validating, and Timely.
5. The application may run on desktop or mobile or both, using any platform supported by Dart and Flutter.
6. Team members will use Pair Programming. Ideal collaborations would be in person, although Zoom’s remote control feature allows for inferior but adequate distributed practice. If working remotely, consider keeping a to-do list in a file in your repository or using GitHub’s project management features.
7. The software must be written in Dart 3.13+ using Flutter 3.47+ and developed within Android Studio. Ensure that only source files are tracked in version control by following the conventional project configuration.
8. Include a README.md file at the root of your project. This file should include, at minimum, a summary of the project, the names of the authors, and the submission report, which is defined below.
9. Your solution must be on the repository’s single mainline branch, which may be called master, main, or trunk at your discretion.
10. Be considerate of the Wikipedia server. Only generate requests when the user asks for answers: do not write a program that “polls” Wikipedia. Follow the MediaWiki etiquette rules, including identifying your client via the user-agent header.
11. Be considerate of the user. Present the results clearly and legibly. Do not generate files on their hard drive. Do not print debugging information.
12. Identify your submission by tagging it in git as “v0.1.0”. This numbering system follows the pattern of semantic versioning. If you need to make a change, and the deadline has not passed, you can tag your patched submission as “v0.1.1”, then “v0.1.2”, etc. (In my opinion, the easiest way to manage this is to create a “Release” on GitHub, which generates the tags for you.)
13. Parse structured data using an appropriate and robust technology such as dart:convert. Don’t rely on naïve String searches.
14. Address all compiler warnings. Suppressing a warning is not addressing it.
15. Follow the Effective Dart: Style rules.

Getting Data from Wikipedia

The technology behind Wikipedia is called MediaWiki, and it has an extensive API for developers. Wikipedia provides an API Sandbox that you can use to learn the API by playing with live data. Doing so helped me come up with the following HTTP request, which pulls down information about the four most recent changes to the Soup page as a JSON document:

https://en.wikipedia.org/w/api.php?action=query&format=json&prop=revisions&titles=Soup&rvprop=timestamp|user&rvlimit=4&redirects

At the time of this writing, the following response was returned:

{"continue":{"rvcontinue":"20260522220157|1355614969","continue":"||"},"query":{"pages":{"19651298":{"pageid":19651298,"ns":0,"title":"Soup","revisions":[{"user":"Kintrob ladio","timestamp":"2026-08-05T10:12:49Z"},{"user":"Macrakis","timestamp":"2026-08-03T22:49:55Z"},{"user":"Paula-lucia-lopez","timestamp":"2026-07-04T02:01:40Z"},{"user":"Comfr","timestamp":"2026-06-26T15:11:48Z"}]}}}}

Fortunately, we can pretty-print this to make it more readable to humans.

{
  "continue": {
    "rvcontinue": "20260522220157|1355614969",
    "continue": "||"
  },
  "query": {
    "pages": {
      "19651298": {
        "pageid": 19651298,
        "ns": 0,
        "title": "Soup",
        "revisions": [
          {
            "user": "Kintrob ladio",
            "timestamp": "2026-08-05T10:12:49Z"
          },
          {
            "user": "Macrakis",
            "timestamp": "2026-08-03T22:49:55Z"
          },
          {
            "user": "Paula-lucia-lopez",
            "timestamp": "2026-07-04T02:01:40Z"
          },
          {
            "user": "Comfr",
            "timestamp": "2026-06-26T15:11:48Z"
          }
        ]
      }
    }
  }
}

This response is in JSON—JavaScript Object Notation—which is the de facto standard language for interacting with Web services. With a bit of reading and reasoning, you can see that the latest revision was made by “Kintrob ladio” on August 5, 2026.

Accessing live data from a Web service is straightforward using Dart’s http package. Reading the relevant official tutorial is highly recommended. Indeed, the Flutter learning resources cover a lot of common cases.

Keep in mind that the best practices for using Wikipedia require that we identify our clients in the HTTP request. Therefore, you should add the user-agent header to your request, as demonstrated below.

final result = await http.read(uri, headers: {
    'user-agent':
    'Revision Reporter/0.1 (https://www.cs.bsu.edu/~pvgestwicki/courses/cs222Fa26; yourname@bsu.edu)'
});

Recommended Approach

As a preliminary step, you will need to configure your work environment. Create an empty repository in our course organization on GitHub, making sure to name it according to the requirements. Then, create an empty Flutter project, set it up to use git for version control, and configure it for TDD by adding the dart:test development dependency. (My preferred approach: run flutter pub add dev:dart from the terminal.) Commit this project to version control, and push the changes to your repository. Then, your partner makes a New Project from Version Control in Android Studio, specifying the URL of your team’s GitHub repository when appropriate. They should be able to clone the project and have an exact replica of it.

Often, when I first clone a Flutter project from GitHub, Android Studio gets a little confused and asks if I want to enable Dart for the project. Don’t do that. Instead, open the project settings, search for Flutter, and make sure your Flutter SDK is properly set. If it is, and then you press “OK,” the problem should disappear. Remember to run flutter pub get to get all your dependencies; this can be done through the terminal or by opening pubspec.yaml and using the IDE button.

Once your basic configuration is done, there are many ways to move forward. The suggestions below will help you get started.

Be sure to review the authoritative definition of Pair Programming. Students frequently come out of CS120 and CS121 misunderstanding Pair Programming due to some of the pedagogical scaffolding that is reasonably put in place in those courses. A more comprehensive treatment of how and why to use Pair Programming is available on Martin Fowler’s site. Of particular interest is Strong-Style Pairing, whose rule is, “For an idea to go from your head into the computer it MUST go through someone else’s hands.”

TDD is mandated by the nonfunctional requirements, so a critical step is transforming the functional requirements into SMART tasks. Be diligent in discussing this task list with your partner. Practicing the decomposition and communication of tasks is a fundamental part of this project.

Because we are following the FIRST principles, unit tests should not touch the network. After all, you cannot control Wikipedia, and so to access it would make your test not Isolated. This means that when you identify a SMART goal related to dealing with Wikipedia data, you can get a snapshot of real data and save it into your project for your tests to process.

Similarly, by SRP, your code that interacts with the user should be separate from the code that constructs URLs, connects to the network, and parses the results. The code for each of these domains changes for different reasons and so is a different responsibility.

Without further ado, here are some steps that could lead to task lists. It is not the only way forward, but you may find it helpful.

1. Choose a page on Wikipedia, determine what URL will give you its most recent editor, and get that data as JSON. Copy this into a test resource file. Write a learning test to ensure you can read the name of the first revision author from your test data. (A learning test is a bona fide unit test that does not touch any production code. It is used for you to explore an API, and it can be deleted once the relevant production code is in place.)

2. Start a RevisionParser class to parse a String into revision data. To get started, test that its parse method, given the test data already downloaded, returns the name of the first revision author as a String.

3. Bringing to mind our discussion of domain modeling in class, observe that you don’t really want a String from your parser but rather a revision. In our case, this revision could be a data transfer object (DTO). With that in mind, refactor RevisionParser so that the parser returns a Revision object instead. This improves encapsulation and abstraction, even if the first pass of Revision still only contains the reviser’s username.

4. At this point, the model works for a “happy path” story—the case where nothing goes wrong. This means you could slice through the whole layered architecture by creating a minimal GUI. Sketch the UI, breaking it up into appropriate widgets using the techniques you learned in the Building Layouts tutorial. Create an interface in which the user types into a text field, taps a button, and gets their result. FutureBuilder can give an elegant solution to the problem of dealing with asynchronous network I/O, although it may appear intimidating at first glance, and its use is not required.

With an end-to-end prototype in place, you can start dealing with some of the exceptional cases. How will you deal with synchronization, so that the UI does not allow a change to the search term while the search is running? How will you deal with redirects? The next steps are up to you.

Formal Evaluation

When working on a software development project, there are three related constraints that you can manipulate: time, quality, and scope. For us, time is fixed since we have exactly two weeks to do the work. The quality, manifesting as the nonfunctional requirements, maps directly to the learning objectives of the course and is therefore nonnegotiable. The only lever we can manipulate, then, is scope. Our scope is measured as user stories, which is common practice for agile teams.

These observations yield the following grading scheme. Your grade is the highest row for which you have satisfied all the requirements.

Your submission report is a section within your README.md file. It supports formal evaluation of your work by clearly stating what grade your team has earned. For example, a submission report might say, “We completed the first two user stories and met all nonfunctional requirements, and we therefore have earned a B.” Another might say, “We completed the first and third user story but did not use Pair Programming, so we earned a D.”

Final Project

Introduction

Your final project will be your focus for the majority of the semester. You will be working with a team over three iterations, each of which will produce an executable release.

Schedule of Deliverables

Pitch

Each team will prepare a project pitch. The pitch will be given as a presentation to the class.

• Share a project summary—one or two sentences that succinctly and accurately describe the endeavor.
• Identify the target audience for the proposed project and the need that it addresses. Depending on your proposal, you may need to consider factors such as age, location, education level, interests/hobbies, native language, and access to technology. The definition of the target audience must be specific enough to allow you to test your project with representatives from the audience. For example, “students” includes an enormous variety and so is too broad. “Non-traditional students at Ball State University” and “Chinese Computer Science majors in the 1+2+1 Program” are both more reasonable targets since you can unambiguously identify individuals for focus group discussion or acceptance testing.
• One to three key features of your proposed project.
• State the technology you propose to use to complete this project. Flutter and Android Studio are strongly recommended but not required. Using the object-oriented paradigm, Clean Code, and GitHub are required.
• Provide a sketch or mock-up of your user-interface.

Each required element of the pitch will be evaluated using the established course grading scheme. A pitch is satisfactory if each of the four parts is essentially correct. Elements that are middling can be resolved via direct team communication with the professor. If any element is essentially incorrect, then the team will give a revised pitch during the next available class meeting.

Plan

Once a pitch is accepted, a team can begin work on the project plan. The project plan will be a document in our shared folder on Google Drive. Specifically, there will be a top-level folder called “Final Projects,” and in that folder, you will create a folder for your team’s project. Inside that folder, you will have a document called “Project Plan”.

To construct the project plan, first create at least three user stories that express the functional requirements. These will be documented using Mike Cohn’s format; see the two-week project stories for examples. Remember that these stories are from the user’s perspective, and the conditions of satisfaction provide the acceptance criteria for knowing when the story is complete. “Epic” stories that are too big to complete within one iteration must be divided into smaller stories. Having many small stories is better than having few larger ones. Prioritize your stories to create the product backlog.

Working in priority order, decide which stories the team will complete during the first iteration. Clearly indicate in the plan document where you draw the line. Notice that you’re not planning future iterations here: you’re only committing to a subset of stories for the upcoming iteration. The stories above the line comprise the iteration backlog or, borrowing terminology from Scrum, the sprint backlog. The stories under the line comprise the product backlog.

Here are two important rules about how to approach the project once the plan is in place:

1. Only work on stories in the iteration backlog.
2. The project belongs to the whole team: any person can work on any feature.

Functional Requirements

The functional requirements of your project are articulated through your user stories. Our learning objectives impose one additional constraint: each iteration must include some new computational feature at the model level. It is insufficient to spend an entire iteration in the view layer.

Nonfunctional Requirements

Each project is to be developed by a team of three to four students from the same section. Projects must use an object-oriented approach, following Clean Code as well as the conventions for your language and platform. Following Clean Code implies using TDD, and we retain our CS222 exemption for view-layer classes.

All projects will be hosted within the class’ organization on GitHub. Each will have a README.md file in the root of the repository that lists the team members and provides any special build or execution instructions.

Your production code must be in the default repository branch. That branch must be the single mainline development branch, and it may be named master, main, or trunk.

Use a standard git configuration and process. This will include the following factors:

• Every commit has specified your committer name properly using the standard format, which is your natural name followed by your email address in angular brackets—for example, “Nick Soapdish <Nick.Soapdish@bsu.edu>”. You can configure this systemwide in git following the getting started guide; Windows users will want to install Git for Windows first.

• Commit messages follow the best practices for writing commit messages as documented by Chris Beams. The subject line of a commit message finishes the sentence, “If applied, this commit will…” The following rules are followed:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

  You can verify this configuration by looking at your git logs. You can even modify old commit messages that violate the conventions, although this is only safely done before pushing.

Confidential data such as API keys and tokens must be securely managed. This means, for example, that such data are never stored in a repository. They belong in configuration files that are loaded at start-up and not in your program source code.

Your increment should be a usable, stable software system that implements a subset of your user stories. This is known as an executable release or a potentially shippable product.

Mark your submission as complete by making a release for it on GitHub. Tag these using semantic versioning as 0.1.0, 0.2.0, and 0.3.0, respectively. As in the two-week project, you may increment the patch number if you need to make a change prior to the deadline.

Each increment must be tested by at least five representatives of the target demographic who are not on the project team. This practice constitutes acceptance testing, and it is done by giving testers specific tasks to accomplish using your system and observing their interaction with your system. The tasks should come from your user stories. We will discuss additional details and pointers about acceptance testing in class.

Personal Progress Reports

Each student will complete personal progress reports periodically throughout the final project. These will be submitted in hardcopy at the start of the meeting they are due, following the schedule provided above. The personal progress report is a way to help me understand what you individually have done as part of your team. Hence, a personal progress report is always in the first-person singular (“I”), not plural (“we”).

These reports are confidential and are to include the following details:

1. What did you agree to work on this week? What did you complete this week?
   
   Notice that there are two questions, and a satisfactory report will explicitly address both.

2. Did you meet your weekly time commitment into the final project?
   
   You should be spending 7–9 hours each week on the final project. The three hours of class meeting count toward this even if the day’s presentation veers from the final projects. A satisfactory report will clearly and specifically answer the question as stated.

3. Whom did you help this week? Who helped you?
   
   These details help the instructor, as supervisor over all teams, to get an understanding of how teams are functioning and whether intervention is necessary.

4. What tutorials or resources did you use this week?
   
   Be specific and include links. As above, this gives the instructor important contextual information about how teams are spending their time.

Presentations

In the meeting following each iteration’s deadline, each team will give formal presentation to the class. The presentation is to be under ten minutes long and must include the following.

• A demonstration of the executable release.
• A description of the user stories that were completed.
• A summary of acceptance testing results.
• A technical lesson for your classmates. Explain a particular challenge you faced, how you addressed it, and your reflection on that approach. Be specific: show code. This is an opportunity to share something interesting with your classmates who are outside your team.

Always use dark text on a light background for slide-based presentations unless you have complete control over the room lighting. If showing anything inside of an IDE, be sure to set up a large font size and light mode before the presentation.

Reflection Essays

At the end of each iteration, each team member will write an essay reflecting on the past iteration. This essay should draw upon experiences from the past iteration to directly and explicitly address one of the course’s essential questions that are given in the course overview page. These essays will be submitted confidentially on Canvas. Refer to the tips page for more information about how to write good essays.

These reflection essays are to be delivered in hardcopy at the start of the meeting in which the increment is presented.

Self- and Peer-Evaluations

Each member of a team will conduct a rubric-based self- and peer-evaluation at the end of each iteration following the link that is available on Canvas. The rubric is shown below.

Grading

Your software increment will be evaluated primarily on the nonfunctional requirements since these relate most closely to our learning objectives and essential questions. That is, you might think of the functionality of your final project as the motivating context to demonstrate understanding of the nonfunctional requirements.

Each deliverable will be evaluated on a four-point scale following the principles of triage grading. In summary, each will be evaluated using the table below.

Your raw iteration score constitutes 10% presentation, 10% reflection essay, 10% personal progress reports (averaged), and 70% project. Your contribution score is the sum of the medians from the self- and peer-evaluation rubric. Your score for the iteration is the minimum of the contribution score and raw iteration score. Practically speaking, this means that your iteration score is capped by your teamwork efforts.