2021 Reengineering Project - MegaMek

(Last Update: 2021-03-08)

Target Application

MegaMek is a computerized version of the BattleTech tabletop game, a tactical turn-based sci-fi boardgame for 2+ players, with tanks, infantry, warships, and giant robots. MegaMek is a live project with an activity community working on it, the last commit on its repository is just a few days old.

Links:

Assignment

1. Contextualization for Strategic Refactoring

Let's suppose the hypothetical Company X wants to create a dedicated server for competitive MegaMek matches. Although Megamek already has features to run as a dedicated server, currently there is no form of rating for Players. In competitive gaming, a rating system is important to calculate the relative skill level of the participants. Basically, Company X wants to host matches and rank the participants based on their rating. Moreover, the competitive matches do not discriminate against Artificial Intelligence (AI), therefore it is possible for both human and bot Players to compete (i.e., both humans and bots have ratings). The ratings should be updated after each match based on the results. For example, a player who lost the match will decrease in rating according to a certain formula, and similarly, the winning player rating will increase according to a certain formula.

Your assignment as a software reengineering team working for Company X is to restructure the current code of MegaMek to support a rating system for Humans and Bots players. Company X still has not decided on the exact formulas for its Player rating system, and you need to consider that in your reengineering activities.

If you need a concrete example of a rating system to better understand the context, you can imagine something similar to the Elo Rating System.

Here is a video lecture, on the project assignment and the pre-condition report.

2. Getting Started

Please pay attention to the following getting started instructions. You need to send an email to Henrique Rocha and John Businge with:

Subject "Reengineering 2021 - MegaMek" if you intend to work on this suggested software; or "Reengineering 2021 - Custom Project" for a custom project proposal. Please try to contact us sooner than the deadline (March 24, 2021) if you want to work on a custom project.
Message Body:

The full name of the members in your group (including yours). Remember, a maximum of 3 people but you are allowed to work with less than 3 if you want to.
If you choose to work on a custom project, then you will need to explain/motivate why this project would allow you to demonstrate your reengineering skills.
Attach the pre-conditions report (PDF format) in your message.

Your Pre-conditions Report should contain the following:

Project Name (to be sure you are working on the suggested project or a custom one)
Full Name of all the members in your group
Link to your GitHub repository (which show to us you already forked the repository)

The members are set as collaborators to the GitHub project.

The TAs were invited as collaborators (Henrique's GitHub Id, and John's Github Id).

Demonstrate the ability to build the project. For this, we want a statement from the group attesting they managed to successfully build the project. You can also attach a screenshot of your IDE with the project source and a message like "build successful".
Simple Class Diagram of the Player class. A simple class diagram has only the name of the class and its interactions with the other classes (there are two examples in JPacman repository in the "docs" folder). This is to reinforce your initial understanding of the system. You only need to focus on the Player class and the classes that are called by Player. There is no need to go deeper into the class structure (i.e., if Player calls Class X, and Class X calls Class Y, then you do not need to show Class Y since it is not being called directly by Player). We are not going to evaluate your strictness to the proper UML notations, therefore focus on modeling and understanding classes interactions.

For custom projects, this will be a Simple Class Diagram of your system. If your system is big, we can negotiate a smaller subset of the system for this diagram. In any case, you will need to contact the TAs sooner to set up the details.

[Optional] A rough planning of the scope and goals. As you noticed the project refactoring is open to interpretation (this is on purpose). Therefore, is up to you, students, to plan the scope for your project. It is entirely possible for different groups to have different scopes and planned activities based on this assignment.

3. General Coding Instructions

In order to work on this assignment, the following coding/repository instructions apply:

Fork the GitHub project (link above), and clone the source code for your team to work on it. In the Documentation webpage, you can find further instructions on how to build the software (adapt accordingly, as many open source projects are a bit careless with keeping their documentation up-to-date).
If you are working on this assignment as a group, then all members should be added to the repository as collaborators.
Add the teaching assistants as collaborators to your fork (Henrique's GitHub Id, and John's Github Id).
Commit/push your changes regularly providing information on the activity performed. Any "single" activity that requires file maintenance must be committed as a single commit with a simple description of the maintenance performed. For example, if you change the system to remove a God Class, your commit should be:

refactoring God Class or fixing God Class (Extract Class) or fixing God Class (removing code clones)

Another example, let's suppose you also introduced new tests along with the refactoring:

refactoring God Class + new test added

Of course, pushing the tests on a separate commit would also be acceptable (actually, it would be better to do so).

It is not considered good practice to commit a big chunk of modified files without providing a reason that explains why those files have been modified. Therefore, try to split your commits into smaller units (that may help with the grading).

Your GitHub commits history will be evaluated. Therefore be sure to commit and push regularly.

Be sure to commit/push the final version of your reengineering project before the final deadline. The final commit will be considered for evaluation as part of your assignment submission.

4. Development Activities

Then, more specifically, we ask you to perform the following activities, and report about these in your project report:

[I. Design recovery]

Describe the current design implementation of the selected feature in the current Software. Clearly indicate how this design is located in the architecture of the project.

[II. Redesign]

Compose a generic design that describes how the new functionality / feature should be integrated and how the design handles the interaction with the rest of the system. It should be clear that the new design not only supports the new feature but also does not severely impact the code quality.

It will be necessary to redesign the test suite in such a way that it can cope with the new feature and design.

[III. Management]

Estimate the effort required for (i) refactoring towards the new requirements; and (ii) changing/extending the tests.

[IV. Refactoring]

Refactor the current implementation of the Software such that it can handle the new feature.

Adjust/extend the tests of the project to preserve their effectiveness and coverage during and after refactoring.

You will be required to perform a number of techniques presented during the lab sessions. These are:

Analyzing: Metrics and Visualization; Duplicated Code Analysis; and Mining Software Repositories.
Restructuring: Testing; and Refactoring.

This project emphasizes the sound, systematic analysis of the presented problem, the associated solution space, and the chosen solution(s). The software reengineering sessions are composed in such a way as to prepare you for such a project. We stimulate you to assess the benefits and drawbacks of the techniques presented in the lab sessions and ask you to exploit the analysis techniques wisely. You are free to use alternative analysis techniques and tools as much as you deem necessary.

What concerns the refactoring-part, we emphasize the use of tests. Our minimum requirements are:

Determine the extent to which the current tests provide feedback on your future refactoring-steps. Quantify this (i.e., show coverage information).
Compose an argument discussing why the tests are adequate/inadequate for your chosen refactoring scenario. If inadequate, adjust the tests as needed. Be efficient with regard to the time invested in testing.

5. General Evaluation

To show that you have passed the assignment, you will have to demonstrate the following:

You possess the knowledge to plan and selected the appropriate reengineering patterns for your project activities.
You have made a selection of analysis techniques (e.g., duplicated code analysis, mining software repositories, metrics and visualization as seen in the lab sessions, but others are allowed as well), and have applied these techniques in a sound, systematic manner. You have indicated clearly (using screenshots, results of the interpretation of the output of the techniques) how you have used the results of these analysis techniques.
You have performed the above activities (decomposed into (i) Design Recovery; (ii) Redesign; (iii) Management; and (iv) Refactoring) and discussed them in your project report.
The restructurings you have applied are behavior preserving:

You can demonstrate the mapping between each of the classes from the original structure with the new structure.
The compilation process succeeds flawlessly.
The tests run without flaws and show increased testing coverage making it more reliable.

The introduction of the new design clearly indicates the project is ready to be released in a language of choice. You are not supposed to carry out the refactoring process completely. Select and execute a set of refactorings that sufficiently illustrate your proposed solution.
The report is written in a clear manner detailing all the steps and reasoning for the project. Remember that the report is the document that registers all your work. Thus, it is the most important artifact for the evaluation process.

For a more precise on-point view of the evaluation criteria, please look over the check-list (for each report) on the course's main page.

6. Report

Aspects that we typically like to see addressed in the final report are:

Context: Briefly discuss the context in which you are running your project (do not just copy verbatim the text on 1. Contextualization).

The Problem at Hand: Clarify the problem at the base of the project, and indicate its intrinsic difficulties (again, do not just copy the assignment problem description, elaborate based on your chosen interpretation, goals, and scope).
Reengineering Patterns: You explicitly state the patterns (from the OORP book) that you selected and used throughout the project.
Project management: Demonstrate how you have organized the work, and how you are controlling it (instead of the work controlling you!)

Scope: What are the boundaries of your project? What is not included in the project?
Risks: Which risks were envisioned, and which have been mitigated? What is the priority of the risks that still need to be mitigated? E.g., which external dependencies might have an effect on your outcome? Which alternatives have you prepared in case this risk instantiates?

Software reengineering:

Tests: How can you verify that you satisfy the requirements? Which testing strategy have you selected, and what are the arguments for this selection? How confident are you that your solution satisfies the requirements?
Quality assurance: What are the non-functional requirements? E.g., how do you differentiate between a good and a bad solution?
Refactoring: Which refactorings did you perform on the project? Why is it better now? How does your refactoring help to support the new intended features?

Those are aspects we like to see addressed/tackled/discussed/explained/presented in the Final Report. In the Intermediate Report, we expect less detail. However, groups that try to start addressing some of the above concerns most often have a better Intermediate Report. In the Pre-conditions Report, although not necessary, it might be better if your group starts to plan the scope and goals for the project.

Please also keep in mind and check the Report Guidelines and the Evaluation Checklist on the main page.

7. Final Remarks

If you have any questions about the project or the report, please contact the teaching assistants.

Note: similar to previous years, it is once again possible to submit your own project proposals. These proposals will be approved in case they provide a well-structured exercise on the reengineering techniques presented in the lab sessions. You can always propose to reengineer another software system, for example, the software system used in your thesis, or written for another case.