Developer Guide

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

Go to File > Settings… (Windows/Linux), or IntelliJ IDEA > Preferences… (macOS)

Select Editor > Code Style > Java

Click on the Imports tab to set the order

For Class count to use import with '*' and Names count to use static import with '*': Set to 999 to prevent IntelliJ from contracting the import statements

For Import Layout: The order is import static all other imports, import java., import javax., import org., import com., import all other imports. Add a <blank line> between each import

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

After forking the repo, the documentation will still have the SE-EDU branding and refer to the se-edu/addressbook-level4 repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to se-edu/addressbook-level4), you should do the following:

Configure the site-wide documentation settings in build.gradle, such as the site-name, to suit your own project.

Replace the URL in the attribute repoURL in DeveloperGuide.adoc and UserGuide.adoc with the URL of your fork.

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

Coverage reporting could be useful for a team repository that hosts the final version but it is not that useful for your personal fork. Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

Having both Travis and AppVeyor ensures your App works on both Unix-based platforms and Windows-based platforms (Travis is Unix-based and AppVeyor is Windows-based)

When you are ready to start coding,

Get some sense of the overall design by reading Section 2.1, “Architecture”.

Take a look at Appendix A, Suggested Programming Tasks to Get Started.

The achievement mechanism is facilitated by AchievementRecord. TaskManager is added with an AchievementRecord on top of the original UniqueTaskList.

AchievementRecord stores the achievement information of the user internally. These information include the current Xp, current Level, total number of tasks completed across all time, as well as the xp earned and number of tasks completed by the user today and this week. To facilitate the tracking of the time-based achievements(namely xp earned and number of tasks completed by today and this week), AchievementRecord also stores the date and time when the time-based achievement fields should be reset.

AchievementRecord also contains a field displayOption that specifies which set of achievement information should be displayed on UI. The field is updated through the achievements all-time, achievements today or achievement this week commands.

The storage of the AchievementRecord is facilitated by XmlAdaptedAchievementRecord which is saved together with the list of XmlAdaptedTask in the SerializableTaskManager.

Integration of AchievementRecord in Model component:

An updateTaskStatus method is implemented in ModelManager and exposed in the Model interface, this method is called in the execution of complete command. Upon completion of a task, the status of task is updated to COMPLETED, along with that, the AchievementRecord is also updated with the new xp. Current xp, number of tasks completed increases, current level is recalculated and updated to match current xp. As the time based achievement fields should be reset every day or week, checks are performed and the fields are reset if necessary. Xp earned and number of tasks completed today and this week is then increased as well.

An updateAchievementDisplayOption method is implemented in ModelManager and exposed in the Model interface, which is called in the execution of the achievements command. Before the displayOption field of the AchievementRecord is updated, checks are perform to reset the time based achievement fields if necessary as well to ensure that they are up to date. The displayOption is then updated, an AchievementsUpdatedEvent is posted to notify UI, who then display the set of achievement information as specified by user’s command.

Sequence diagram of the achievement mechanism:

Activity diagram of the update of daily time-based achievement fields(today’s xp, today’s number of tasks completed):

The achievement mechanism follows the event-driven interaction of model component with Storage and UI components. When a task is marked as complete, both the UniqueTaskList and the AchievementRecord of the task manager is updated to reflect the new status of the task and the new achievement information. A TaskManagerChangedEvent is then posted to EventsCenter and handled by both Storage and UI components to save the changes and update the status bar.

On top of the TaskManagerChangedEvent, an AchievementsUpdatedEvent is posted by the Model component every time the AchievementRecord is update(on task completion or change of display option). This event is handled by the AchievementPanel UI component which then update the achievement information displayed.

Aspect: Associations Among TaskManager,UniqueTaskList and AchievementRecord

Aspect: Managing display option of AchievementRecord.

The batch completion mechanism is facilitated by CompleteLabelCommand. It extends CompleteCommand and encapsulates the internal logic of finding completable tasks via a supplied Task<Predicate>. Additionally it is able to complete and rollback multiple tasks atomically.

These are the methods in the CompleteLabelCommand class supporting the batch completion:

Premise: The application has several tasks tagged with the label: many.

Step 1. The user executes complete l/many command to complete all the tasks labelled many.

Step 1.1. The argument String is passed to the CompleteCommandParser, which checks to see if the user’s input contains a label, then calls CompleteCommandParser#parseLabel(…​). As a result a new CompleteLabelCommand instance is created. It consumes a LabelMatchesAnyKeywordsPredicate which will only test true against a Task containing a many label.

Step 1.2. A chain of event triggers, ultimately calling CompleteCommand#execute(…​) for the created instance. Subsequently CompleteLabelCommand#completeAllTasksReturnStringOfTasks(…​) is called which encapsulates the logic for updating all valid completable tasks matching the supplied predicate.

Step 1.2.1 If all tasks are updated successfully, Model#commit() will be called.

Step 2. The user sees all tasks previously displayed on the screen which matches the label change its status to COMPLETED

Extensions

Step 1.2.1.a If all tasks are not updated successful, Model#rollback() will be called. All uncommitted changes will be reset to the current state pointed to in taskManagerStateList.

Step 1.2.1.a1 Then user will see a relevant error message reporting what went wrong.

Allows for any uncommitted changes to be discarded.

When VersionedTaskManager#Rollback() is called, the current data is reset to the state of the latest commit. Internally, VersionedTaskManager#resetData(…​) is called to reset the data to the commit pointed by the currentStatePointer in the taskManagerStateList.

Calls to the Commons/Event component has been omitted for brevity.

The dependencies of a task is modelled by an embedded Dependencies object in the task. This object represents dependencies with a hashset that contains the hashcodes of the tasks that the task is dependent upon.

The dependencies between tasks are added or removed using the dependency command. If a given task A is dependent on a given task B, task A is the dependant task while task B is the dependee task.

When deleting a task, all dependencies to the deleted task will be removed. When editing a task, all dependencies to the edited task will be updated with the hashcode of the new edited task.

Activity diagram for the dependency command (dependencies are toggled using the command)

The DependencyGraph is the graph representing the dependencies between the task objects. A graph model needs to be created so useful functions can be implemented such as cyclic check, topological sort, or a depth first search of the graph.

Sequence Diagram of the Show Topological Order Command (DependencyGraph on the right hand side of diagram)

DependencyGraph is instantiated whenever it is needed. Transformations such as inverting the graph or pruning COMPLETED tasks from graph.

Effective Due Date (EDD) is a derived field in the UI. It is the earliest due date among all tasks directly or indirectly dependent on the task, including the task itself.

Steps to find effective due date of task A:

Diagram for effective due date implementation

Note: comparison of due date with EDDs of children in square brackets

Table for effective due date implementation

Time is of key importance when dealing with the TaskManager. We implement and represent time using the ubiquitous Date class in Java. The class DueDate internally uses the Date class, and harnesses built in capabilities such as date comparison. The precision of time for tasks is to the minute, that is the AddCommand can accept a DueDate accurate to the minute.

A check on whether any of the tasks are overdue is done before the execution of every command.

The list command accepts filters that either filter based on the due date of the tasks (relative to the current date) or the dependencies of the task. This is done using predicates that are given to filter the task list.

The Task Manager owns a GameManager object, which handles the core logic of gamification. All xp calculations are handled exclusively by the current GameManager.

The GameManager, in turn, owns a GameMode object. GameMode is implemented as an abstract class, and specific implementations of game modes must extend the abstract GameMode. The GameMode handles the actual appraisal of tasks for xp, delegated from the GameManager. Individual variations of GameMode will contain their own logic to determine xp earned, accessible through appraiseXpChange(Task taskFrom, Task taskTo).

When a task is completed, ModelManager::updateTaskStatus(Task target, Task updatedTask) is used to change the target task into the updated task. TaskManager::appraiseXpChange(target, updatedTask) is then called (from the current versionedTaskManager instance).

At this point, the TaskManager calls GameManager::appraiseXpChange(Task taskFrom, Task taskTo), passing control to the gamification component.

The GameManager delegates the xp calculation to its owned GameMode through GameMode::appraiseXpChange(Task taskFrom, Task taskTo). The GameMode first checks if the tasks are valid. In particular, the tasks must be the same tasks (that is, they have the same fields), and the status change must be a valid change (e.g. from IN_PROGRESS to COMPLETED, and not something like COMPLETED to OVERDUE).

Following that, the GameMode performs the specific calculations unique to each GameMode, to determine the xp to be awarded.

The current GameManager is persisted in WatchOver’s storage.

The XmlSerializableTaskManager contains a XmlAdaptedGameManager, to capture the state of the GameManager, allow persisting state between sessions, and take advantage of the version control to allow undoing and redoing of changing the game mode.

Four fields are written to file:

The game mode is serialised as the SimpleName of the GameMode subclass in the stored GameManager.

The period is the time before the due date at which the xp awarded by DecreasingMode and IncreasingMode will start to fall or rise, respectively. Other modes ignore this field.

The lower and higher bound of xp awarded are the scalings to which the game modes peg their xp awards, used by all existing game modes.

Using these fields, the GameManager state can be fully reconstructed.

If an invalid game mode is found written to storage, then the invalid data is ignored and a new default GameManager, using the default FlatMode set at medium difficulty, will be created, overwriting the invalid data.

These are tests involving the GUI. They include:

System Tests that test the entire App by simulating user actions on the GUI. These are in the systemtests package.

Unit tests that test the individual components. These are in seedu.address.ui package.

These are tests not involving the GUI. They include,

Unit tests targeting the lowest level methods/classes. e.g. seedu.address.commons.StringUtilTest

Integration tests that are checking the integration of multiple code units (those code units are assumed to be working). e.g. seedu.address.storage.StorageManagerTest

Hybrids of unit and integration tests. These test are checking multiple code units as well as how the are connected together. e.g. seedu.address.logic.LogicManagerTest

Use case ends.

Use case ends.

Use case ends.

Use case resumes at step 1 in MSS.

Use case resumes at step 1 in MSS.

Use case ends.

Use case resumes at step 1 in MSS.

Use case resumes at step 1 in MSS.

Use case ends.

Use case resumes at step 1 in MSS.

Use case ends.

Use case resumes at step 1 in MSS.

Use case resumes at step 1 in MSS.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.

Use case ends.