PocketProject - 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,

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/pocketproject repo.

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

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).

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

When you are ready to start coding,

As dates are widely used throughout the application, it is important that the user is able to easily input any target date but at the same time retain some flexibility so that it is more user-friendly. Therefore, the dates used in the Pocket Project supports 2 main formats as shown below.

Fixed Date Format Format(s):
1. DD/MM/YYYY

Flexible Date Format Format(s):
1.today/tomorrow/yesterday
2.this/next/last week DAY_OF_WEEK
3.this/next/last month DAY_OF_MONTH

The section details how a fixed and flexible date format is parsed and processed.

Refer to the Activity Diagram above while reading the summary below so as to have a visual representation of what happens.

To simplify the explanation, the process can be summarized into the following key points:
1. A check is first made to determine if the input is a fixed or flexible date format. This is done by checking for the presence of a / in the input.
2. If it is a fixed format input, a check is made to determine if it conforms to the DD/MM/YYYY format.
3. If it is a flexible format input, the input is parsed and the PocketProjectParser identifies keywords to determine the appropriate methods to call from the model. The target date is then formatted into the DD/MM/YYYY format.
4. Regardless of the initial format of the input, the current string would represent the form of DD/MM/YYYY at this stage. The validity of the date is then checked.

Refer to the code snippet below to see how the validity of the date is verified.

As can be seen above, the code not only checks if the selected day falls within the maximum number of days in a month, but it also checks for leap years. This ensures that only valid calendar dates are accepted as a viable input.

Potential Design 1
User keys in Wednesday, next Wednesday, last Wednesday to denote the current, next and last week’s Wednesday respectively

Potential Design 2 (Selected Implementation)
User keys in this week 3, next week 3, last week 3 to denote the current, next and last week’s Wednesday respectively

The second design was chosen as the first one is subjective to an individual’s language use. For example, if today was Monday, and a person was to mention next Wednesday, some people may be thinking of the Wednesday in 2 days time whereas others may be thinking of next week’s Wednesday. Thus to remove confusion, the keyword this/next/last was added. In addition, instead of spelling out the days, users can key in the day number instead. This speeds things up and also reduces errors due to spelling mistakes in the name of the day.

This feature focuses on the adding of employees and milestones to a selected project. It supports two commands which are explained below.

In addition, the AddToEmployeeCommand class and AddToMilestoneCommand class is abstracted into a AddToCommand class which inherits from Command class. This allows for further functionalities to be added while conforming to the Open-Closed Principle.

Refer to the Class Diagram below for a better visualization of the inheritance relationship.

The section details how a AddToCommand is parsed and processed.

Refer to the sequence diagram above to better understand how the AddEmployeeTo Command works. The diagram shows the sequence when a addto Apollo employee 1 is executed.

To simplify the explanation, the process can be summarized into the following key points:
1. The PocketProjectParser parses the string received and uses the addto keyword to identify that the input is linked with the AddToCommand class.
2. The AddToCommandParser then identifies the type of AddToCommand that is being executed and the arguments involved.
3. The AddToCommandParser then creates the AddEmployeeToCommand/AddMilestoneToCommand object and this is passed on to the LogicManager for execution.
4. The command execution will check the validity of the arguments and then call the methods of the Model component to add the corresponding employee/milestone to the project.

Potential Design 1
The idea is to have only 1 parser ,PocketProjectParser, which receives and parses the whole input string before constructing the relevant command.

Potential Design 2 (Selected Implementation)
The idea is to have a total of 2 parsers where the first parser, PocketProjectParser identifies the addto key word and the rest of the input string is then parsed by the corresponding second parser, AddToCommandParser.

The 2nd design was chosen as there is better abstraction of the details and it also allows further functionality to be add on top of the implemented parser. If future developers want to add more objects to the project, they can simply make use of this AddToCommandParser to handle different inputs. Choosing this design was a good choice as it helped with the implementation of adding user stories and project tasks to a project after this was initially constructed.

The following additional feature is scheduled to be implemented in future versions.

The commands will be processed in the same way without any other changes.

The removing of employee,milestone or user story from projects is facilitated by the model component of the PocketProject. This feature currently supports these three commands:

These operations are supported by the methods in the Model interface: Model#removeEmployeeFrom(Project, Employee), Model#removeMilestoneFrom(Project, Milestone), Model#removeProjectTaskFrom(Project, Milestone, ProjectTask) and Model#removeUserStoryFrom(Project, UserStory). The methods does not take in indices as arguments since the corresponding Employee, Milestone, ProjectTask or UserStory object associated with the Project object would be found by RemoveEmployeeFromCommand#excute(), RemoveMilestoneFromCommand#execute(), RemoveProjectTaskFromCommand#execute() or RemoveUserStoryFromCommand#execute() before the methods of Model are called. The sequence diagram for the execution of the removing of employee from a project is as follows, the sequence for the removal of milestone, project tasks and user stories are similar:

Given below is an example usage scenario and how the removal of employee/milestone/project task/user story feature behaves at each step.

Step 1. The user enters the command view project Apollo'. The app displays the list of employees and milestones in the project named "Apollo" by executing the `view command.

Step 2. The user enters removefrom Apollo employee 1. The LogicManager passes the entered string to the PocketProjectParser. The PocketProjectParser parses the string received and identifies the command as falling under the class of RemoveFromCommand (which constitutes of RemoveEmployeeFromCommand and RemoveMilestoneFromCommand by the removefrom keyword and passes the rest of the string to the RemoveFromCommandParser to identify which type of RemoveFromCommand is being executed and what are the arguments. The RemoveFromCommandParser then creates command object and passes it to the LogicManager to be executed. The command execution will check the validity of the arguments and then call the methods of the Model component to remove the corresponding objects.

Step 3. The user executes 'removefrom Apollo milestone 2'. The execution of this command is similar to step 2, just that the type of object changes from Employee to Milestone.

This feature allows editing of several components which are under project and is mainly facilitated by the model component. This feature supports 3 main commands:

The EditProjectCommand Parser differentiate these 3 commands based on the COMMAND_KEYWORD which are info, milestone and userstory.

All these 3 commands are inherited from the EditProjectCommand as shown in the diagram above. This allows flexibility as more edit project command can be easily added when there are new components added to the project.

The following sequence diagram shows how edit project info command works:

Given below is the explanation of what happens when the user enter the edit project Apollo info n/Gemini d/12/05/2019 command based on the diagram above:

The working mechanism behind EditProjectMilestoneCommand is similar as well. Instead of replacing the whole project, only the milestone list in the project is edited by replacing the milestone at the given index through the Model#setMilestone(milestoneToEdit, editedMilestone) method.

For the current find feature, there are 5 main commands that the user can execute:

The FindCommandParser differentiates these 5 commands based on the COMMAND_KEYWORDS entered by the users (e.g. employee/project/skill/all/deadline) as illustrated in the diagram below.

The following sequence diagram shows how the find employee command works:

Usage Scenario example for find employee:

The working mechanism for find project is similar to find employee. Instead of updating the filteredEmployees, filteredProjects is updated instead to display the list of projects with name consisting the keywords.

For find all command, the predicate is used to check for the matching keywords in the project name , description and client, thereby filtering out any projects that contains the keyword in these components of the project.

For find skill command, the List<Skills>skills from the employee is retrieved as a String to match against the keywords. Then the matched employees are filtered and displayed on the ui.

find deadline uses the ProjectContainsDeadlinePredicate to compare the deadline of the project against the supplied deadline and filter out the projects with deadline earlier or same as the deadline supplied by the user.

For the current list feature, there are 2 main commands that the user can execute:

The ListCommandParser will parse the user input based on the COMMAND_KEYWORD entered by the user, and then execute the appropriate command based on the keyword given.

The following sequence diagram shows how the list employee command works:

Usage Scenario example for list employee:

The mechanism for list project is similar to list employee, apart from the fact that a ListProjectCommand is executed instead.

The displaying of statistics in Pocket Project will be facilitated by the model component. This feature is planned to support 2 main commands:

The operation will be supported by the methods in the Model interface: Model#overallStats() and Model#individualStats(Project). Model#overallStats() will retrieve the data on all the projects/employees to pass to StatsUtil, an utility class to produce a string which describes the status of all projects. Model#individualStats(Project) passes the given project to StatsUtil to produce a string in a similar fashion.

The following sequence diagrams show how the stats command will work:

Overview of all projects:

Usage Scenario example for stats:

The implementation of user stories in Pocket Project is facilitated by the model component, and in particular, the Project class which will store the relevant user stories as a SortedUserStoryList.

Currently, the user stories feature supports the following commands:

In addition, the SortedUserStoryList maintains a sorted order of user stories according to descending importance level of the user story, followed by ascending lexicographical order of the UserStoryUser name.

For example, suppose we have 3 user stories with the following importance level and user names:

In the SortedUserStoryList these user stories would appear in the following order and index:

Since the user stories with users David and Alan have a higher importance level than John, they will appear above John in the sorted list. Afterwards, since Alan is lexicographically smaller than David, it appears before David in the list.

This is to faciliate users to find important user stories by ensuring a neatly ordered list by relevance of the user story.

The following additional features are scheduled to be implemented in future version.

This project task feature enhances the usage of the milestone feature in Pocket Project for keeping track of a project’s schedule by providing you with a list of tasks which needs to be done between milestones. The project task feature is mainly facilitated by the model component, and in particular, the Milestone class which stores the relevant project tasks in a UniqueProjectTaskList. This feature supports three main commands:

Project tasks contain statuses to help you oversee its progress, whether its "Ongoing", "On hold" or "Complete".

The project task commands are supported by the methods in the Model interface: Model#addProjectTaskTo(Project, Milestone, ProjectTask), Model#removeProjectTaskFrom(Project, Milestone, ProjectTask) and Model#updateProjectTask(Project, Milestone, ProjectTask, Status). These three methods take in Project, Milestone and ProjectTask as common arguments. Hence, the correct project/milestone/project task which the commands act on are first located through AddProjectTaskToCommand#excute(), RemoveProjectTaskFromCommand#execute() or UpdateProjectTaskCommand#execute() before the methods of Model acting on the milestone/project task are called.

In this section, I will talk about certain alternatives that could have been taken when designing this feature and why I did or did not use them.

The following features are scheduled to be implemented in a future version of Pocket Project:

The undo/redo mechanism is facilitated by VersionedPocketProject. It extends PocketProject with an undo/redo history, stored internally as an pocketProjectStateList and currentStatePointer. Additionally, it implements the following operations:

These operations are exposed in the Model interface as Model#commitPocketProject(), Model#undoPocketProject() and Model#redoPocketProject() respectively.

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

Step 1. The user launches the application for the first time. The VersionedPocketProject will be initialized with the initial pocket project state, and the currentStatePointer pointing to that single pocket project state.

Step 2. The user executes delete 5 command to delete the 5th employee in the pocket project. The delete command calls Model#commitPocketProject(), causing the modified state of the pocket project after the delete 5 command executes to be saved in the pocketProjectStateList, and the currentStatePointer is shifted to the newly inserted pocket project state.

Step 3. The user executes add n/David …​ to add a new employee. The add command also calls Model#commitPocketProject(), causing another modified pocket project state to be saved into the pocketProjectStateList.

Step 4. The user now decides that adding the employee was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoPocketProject(), which will shift the currentStatePointer once to the left, pointing it to the previous Pocket Project state, and restores the Pocket Project to that state.

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoPocketProject(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the Pocket Project to that state.

Step 5. The user then decides to execute the command list. Commands that do not modify the Pocket Project, such as list, will usually not call Model#commitPocketProject(), Model#undoPocketProject() or Model#redoPocketProject(). Thus, the pocketProjectStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitPocketProject(). Since the currentStatePointer is not pointing at the end of the pocketProjectStateList, all pocket project states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add n/David …​ command. This is the behavior that most modern desktop applications follow.

The following activity diagram summarizes what happens when a user executes a new command:

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Extensions

MSS

Assuming that the employees added here do not exist in the app beforehand.

Deleting a employee while all employees are listed

Deleting a project while all projects are listed