Lim Jun Hup - Project Portfolio for Athletick

1. Introduction

The purpose of this portfolio showcases my contribution to the Athletick project.

1.1. About the team

Our team comprises of five second-year computer science undergraduates from the National University of Singapore (NUS).

This project is a 6 weeks long project for our software engineering module. We were tasked to either enhance or morph a command line interface Address Book application and one of the main constraints for this project is that it has to remain as a command line interface application.

What we decided to do was to morph the existing address book application to a team management application called Athletick. Athletick is designed for captains and coaches of timing-based performance sports to help take and keep track of attendance and performance of their teams. Other main features of Athletick include viewing of the training calendar and performance graph.

My role was to design and implement the code for the undo and redo features. The following sections illustrate these enhancements in more detail, as well as the relevant documentation I have added to the user and developer guides in relation to these enhancements.

Note the following symbols and formatting used in this document:

This symbol indicates important information

`command`	A grey highlight (called a mark-up) indicates that this is a command that can be typed into the command line and executed by the application.
`component`	Green text with grey highlight indicates a component, class, object or method in the architecture of the application.

2. Summary of contributions

This section shows a summary of my coding, documentation, and other helpful contributions to the team project.

Enhancement added: I added the ability to undo/redo previous commands.

What it does
- The undo command allows the user to undo a previous command. The user may reverse this undo command with the redo command.
Justification
- In the event that users have made a mistake or changed their minds about executing a command, the undo command enables them to revert to a version immediately before the mistaken command was executed. If they change their minds again and decide to execute the command after all, then the redo command enables them to do so easily.
Highlights
- This enhancement works with existing as well as future commands.
- An in-depth analysis of design alternatives was necessary to weigh the different alternatives and decide on the implementation for this enhancement.
- The implementation was challenging as it required a full understanding of the major components of the application and the existing features implementations. Also, the enhancement had to be implemented in a way that the future enhancements for any future features are able to be easily integrated into the current implementation.

Code contributed: The links provided show my code contribution for the project. (Reposense, Github Repository)

Other contributions

Project management
- Managed version release v1.3.4 of Athletick to prepare for final production release on GitHub (v1.3.4)
- Introduced Trello for tasks and deadlines management
- Served as the team’s Backend Engineer and assisted in the logic of the program whenever needed
Existing features enhancement
- Implemented Training and Attendance classes (Pull request #63)
- Added the Gender attribute (Pull request #130)
Documentation
- Added documentation for undo and redo for both User Guide and Developer Guide (Pull requests #188, #219)
- Standardised product screenshots for clear and help in User Guide to make it more reader-friendly (Pull request #223)
- Fixed icons bugs and improved on alignment in User Guide and Developer Guide (Pull requests #242, #243)
Community
- Reviewed PRs with non-trivial review comments (Pull requests #210, #225)
- Commented and provided suggestions on other team’s PR (Review)
- Reported bugs and suggestions for other teams (Bug reports and suggestions: 1, 2, 3)

3. Contributions to the User Guide

This section showcases my contribution to the User Guide. They showcase my ability to write documentation targeting end-users.

{Start of extract from User Guide}

3.1. Undoing a previous command : `undo`

This command restores Athletick to the state before the previous command was executed.

Take note that the undo feature only applies to undoable commands. Undoable commands include: add, delete, edit, clear, training, event and performance.

The undo command will not be able to undo non-undoable commands. Let’s say you have executed a list command to list out all the athletes information in Athletick. If you were to execute the undo command now, the undo command will fail because list is not an undoable command, and that no undoable commands were executed before this.

The undo command will reverse the latest command that can be undone. Let’s say you have executed the delete command, followed by the list command. Since list command is not an undoable command, if you were to execute undo command now, you will thus reverse the delete command.

The undo command reverses previous commands in reverse chronological order. Let’s say you have executed the edit command, followed by the delete command. If you were to execute undo command now, you will reverse the delete command. Executing undo again will then reverse the edit command.

Let’s say you have accidentally deleted an athlete’s contact (Mohamad Ali) from your list. Instead of having to re-enter Mohamad Ali’s contact information all over again, you can easily restore all of Mohamad Ali’s details by executing the command undo to undo the delete command that you have just entered.

What you should do

With Mohamad Ali’s contact information deleted, the current list has 7 people. Type undo into the command box, and press Enter to execute it.

Format : undo

What you should see

The result box will display a success message and you can check that Mohamad Ali’s contact information is visible in the list again!

3.2. Redoing an `undo` command : `redo`

This command reverses the most recent undo command.

The redo command can only be executed immediately after an undo command. Let’s say that you have executed the undo command to undo a previous command that you have previously executed. You then execute the list command to view your list. Executing the redo command now will fail because your previous command was not an undo command.

The redo command reverses previous undo commands in reverse chronological order. Let’s say that you have executed the clear command, followed by the add command. Executing the undo command now will reverse the add command. Executing the undo command again will reverse the clear command as well. Following this, executing the redo command will reverse the most recent undo command and re-execute the clear command. Executing the redo command again will reverse the second most recent undo command and re-execute the add command.

Let’s say you have executed the delete command to delete Mohamad Ali from your list. You may undo this action and restore Mohamad Ali’s information by executing the undo command.

Then, if you decide that you want the contact to remain deleted after all, you may very quickly do so by executing the redo command to reverse the undo command that you had just executed.

What you should do

With Mohamad Ali’s contact information, the current list has 8 people. Type redo into the command box, and press Enter to execute it.

Format : redo

What you should see

The result box will display a success message. Furthermore, the list now only has 7 people and Mohamad Ali is once deleted from the list!

{End of extract from User Guide}

4. Contributions to the Developer Guide

This section showcases my contribution to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

{Start of extract from Developer Guide}

4.1. Undo / Redo feature

The undo command enables users to undo their previous commands while the redo command enables users to redo their undone commands.

4.1.1. Undo Implementation

The undo command is facilitated by the HistoryManager. HistoryManager holds the states of Athletick, Attendance and Performance, which are kept in their respective stacks governed by HistoryManager. Furthermore, HistoryManager also holds the Command stack that keeps track of the commands executed by the user.

Each time after the user executes a command, the command will be pushed to the Command stack. Also, following the execution of the command, changes to either Athletick,Attendance or Performance will result in the new state being pushed into their respective stacks.

Given below is an example usage scenario on how the undo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The HistoryManager will be initialised with the initial Athletick, Attendance and Performance state pushed to the respective stacks.

Figure 1. Initial stacks of states

Step 2. The user executes the delete -p 3 command to delete the 3rd person in the Athletick list. The delete command will be pushed into the Command stack. After that, since the delete -p 3 command only alters the Athletick state, the new Athletick state will then be pushed to the Athletick stack while the Attendance and Performance stacks are left untouched as their states remain the same.

Figure 2. Stacks of states after delete -p 3 command

Step 3. The user now decides that deleting the 3rd person in the list was a mistake, and decides to undo the action by executing the undo command. The undo command then executes the undo method in the ModelManager. This pops the latest command from the Command stack and the latest Athletick state from the Athletick stack. It then peeks at the Athletick stack to retrieve the Athletick state before delete -p 3 command was executed.

Figure 3. Stacks of states after undo command

Step 4. After retrieving the Athletick state before delete -p 3 command was executed, we then reset the Athletick state to this retrieved Athletick state. As such, the previous command will then be undone.

The following sequence diagram shows how the undo operation works:

Figure 4. Sequence diagram for undo implementation

4.1.2. Redo Implementation

The redo command is similarly facilitated by the HistoryManager. HistoryManager also holds the undone states of Athletick, Attendance and Performance, which are kept in their respective undone stacks governed by HistoryManager. Furthermore, HistoryManager also holds the undone Command stack that keeps track of the commands undone by the user.

Each time an undo command is executed succesfully, the undone Command will be pushed to the undone Command stack and the respective undone states of Athletick, Attendance or Performance, if affected, will be pushed to their respective undone states.

Following that, how the redo command works is very similar to how the undo command works. As such, you can also refer to the diagrams in the Undo Implementation.

The activity diagram for redo command is as follows:

Figure 5. Activity diagram for redo command

4.1.3. Design Considerations

This section describes the pros and cons of the current and other alternative implementations of the undo and redo features.

Aspect: How undo & redo executes

Alternative 1 (Current Choice): Keep states of Athletick, Attendance and Performance.

Alternative 2: Individual command knows how to undo/redo by itself

Pros

Easy to implement, and easy for developers to understand.

Will use less memory (e.g. for delete -p 1, just save the person being deleted).

Cons

May have performance issues in terms of memory usage.

We must ensure that the implementation of each individual command is correct.

Reason why we chose alternative 1:

Even though the memory usage of Alternative 2 is lesser, we do not feel that this benefit of lesser memory usage outweighs the tedious cost of implementing the alternative.

Furthermore, as we realise that each time the application starts, the memories of the states are cleared. This means that the cost of having alternative 1 is significantly lesser, as the memories of the states do not accumulate. As such, we decided to go with the first alternative.

{End of extract from Developer Guide}