PROJECT: Mod Manager

Overview

This document documents my contributions to Mod Manager.

Mod Manager is a desktop application that assists students in managing tasks, schedules and contacts for their modules. The user interacts with it using a CLI, and it has a GUI created with JavaFX. It is written in Java, and has about 25 kLoC.

Mod Manager is morphed from existing desktop Java application Address Book (Level 3) over a period of 8 weeks by my team of 5 software engineering students.

Summary of Contributions

Given below is a summary of my contributions to Mod Manager.

Major enhancement:

  • Implemented the module management feature.

    • What it does: This feature allows users to add, view, edit and delete modules.

    • Justification: This feature improves the product as it enables users to manage modules easily. It gathers all the information for each module and displays them to the user.

    • Highlights: This enhancement required integration of the other features. It required an in-depth analysis of design alternatives. The implementation was challenging as it required updating the classes, tasks and facilitators when a module is edited or deleted.

Minor enhancement:

  • Refactored person in Address Book to facilitator in Mod Manager.

  • Implemented the ability to bring users to the relevant tabs when commands are executed.

Code contributed:

Other contributions:

  • Project management:

    • Managed issue tracker and milestones for team repo and merged pull requests

  • Enhancements to existing features:

    • Wrote additional tests to increase coverage from 60% to 66%: #121

    • Updated sample data: #183

  • Documentation:

    • Updated introduction, about and upcoming section of User Guide: #24, #126

    • Added module and facilitator feature of User Guide: #10, #174

    • Updated storage component, non functional requirements and testing of general features of Developer Guide: #24, #103, #121, #180

    • Added implementation, use cases and testing of module and facilitator management feature of Developer Guide: #24, #103, #121, #126, #176, #180

  • Community:

    • PRs reviewed (with non-trivial review comments): #81, #98, #128, #139

  • Tools:

    • Integrated Travis, AppVeyor, Coveralls and Codacy to the team repo

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

About

This user guide helps you to master how to use Mod Manager. It explains the features and commands supported by Mod Manager, with examples to illustrate how the application works.

Module Feature : mod

The commands in this section carry out operations on the module list in Mod Manager. Executing these commands will bring you to the Module tab.

Viewing information of a module (Zi Xin)

You can view all classes, tasks and facilitators for a module.

Format:

  • mod view INDEX

  • mod view MOD_CODE

Command properties:

  • Views the module at the specified INDEX or with the specified MOD_CODE. The index refers to the index number shown in the displayed module list. The index must be a positive integer 1, 2, 3, …​

Examples:

You can view a module using the index in the module list. To view all classes, tasks and facilitators for the second module in the module list, you can type the following command:

mod view 2

ModViewBefore1
Figure 1. Before mod view 2
ModViewAfter1
Figure 2. After mod view 2

Alternatively, you can view a module using the module code. To view all classes, tasks and facilitators for the module CS2103T, you can type the following command:

mod view CS2103T

ModViewBefore2
Figure 3. Before mod view CS2103T
ModViewAfter2
Figure 4. After mod view CS2103T

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Storage Component

StorageClassDiagram
Figure 5. Structure of the Storage Component

API : Storage.java

The Storage component,

  • can save UserPref objects in json format and read it back.

  • can save the Mod Manager data in json format and read it back.

Module Management Feature

The module feature manages the modules in Mod Manager and is represented by the Module class. A module has a ModuleCode and an optional Description.

It supports the following operations:

  • add - Adds a module to Mod Manager.

  • list - Lists all modules in Mod Manager.

  • view - Views information of a module in Mod Manager.

  • edit - Edits a module in Mod Manager.

  • delete - Deletes a module in Mod Manager.

Implementation Details

Adding a module (Zi Xin)

The add module feature allows users to add a module to Mod Manager. This feature is facilitated by ModuleCommandParser, ModuleAddCommandParser and ModuleAddCommand. The operation is exposed in the Model interface as Model#addModule().

Given below is an example usage scenario and how the module add mechanism behaves at each step:

  1. The user executes the module add command and provides the module code and description of the module to be added.

  2. ModuleAddCommandParser creates a new Module based on the module code and description.

  3. ModuleAddCommandParser creates a new ModuleAddCommand based on the module.

  4. LogicManager executes the ModuleAddCommand.

  5. ModManager adds the module to the UniqueModuleList.

  6. ModuleAddCommand creates a new ModuleAction based on the module to be added.

  7. ModelManager adds the ModuleAction to the DoableActionList.

The following sequence diagram shows how the module add command works:

ModuleAddSequenceDiagram
Figure 6. Sequence Diagram for mod add Command
The lifeline for ModuleCommandParser, ModuleAddCommandParser and ModuleAddCommand should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.

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

ModuleAddActivityDiagram
Figure 7. Activity Diagram for mod add Command

Facilitator Management Feature

Design Considerations (Zi Xin)

Aspect: Mutability of Facilitator object

  • Alternative 1 (current choice): Create a new facilitator with the edited fields and replace the existing facilitator with the new facilitator.

    • Pros: Preserves immutability of the Facilitator object.

    • Cons: Overhead in creating a new Facilitator object for every edit operation.

  • Alternative 2: Modify the existing facilitator directly.

    • Pros: More convenient and lower overhead to edit a facilitator by setting the relevant fields without creating a new Facilitator object.

    • Cons: Unintentional modification of the Facilitator object.

Alternative 1 is chosen to preserve the immutability of the Facilitator object to avoid unintentional modification.

Aspect: Storage of facilitators

  • Alternative 1 (current choice): Store all facilitators in a single facilitator list.

    • Pros: Will not have to maintain multiple lists. Less memory usage as each facilitator is represented once. Will not have to iterate through multiple lists to find all instances of a particular facilitator when executing facilitator commands.

    • Cons: Have to iterate through the whole list to find facilitators for a particular module when executing module commands.

  • Alternative 2: Store facilitators for each module in a separate list.

    • Pros: Able to find facilitators for a particular module easily when executing module commands.

    • Cons: May contain duplicates as some facilitators may have multiple module codes. Have to iterate through multiple lists when executing facilitator commands.

Alternative 1 is chosen as the design is simpler without the need to maintain multiple lists and can also avoid duplicates in the storage.

Aspect: Reference of ModuleCode in Facilitator object

  • Alternative 1 (current choice): Create a new ModuleCode object for each Facilitator.

    • Pros: Easier to implement.

    • Cons: Existence of multiple identical ModuleCode objects.

  • Alternative 2: Reference each Facilitator to the ModuleCode in the Module list.

    • Pros: Only require one ModuleCode object per unique ModuleCode. Can support editing of module codes more easily.

    • Cons: Have to iterate through the module list to find the module code for the facilitator.

Alternative 1 is chosen because of ease of implementation due to time constraint.

Appendix C: Use Cases

Use case: UC04 - Edit module

MSS

  • 1. User requests to edit a module and provides the index or module code and the new description.

  • 2. Mod Manager edits the module.

    Use case ends.

Extensions

  • 1a. The given index or module code is invalid.

    • 1a1. Mod Manager shows an error message.

      Use case resumes from step 1.

  • 1b. The new description is invalid.

    • 1b1. Mod Manager shows an error message.

      Use case resumes from step 1.

Use case: UC05 - Delete module

MSS

  • 1. User requests to delete a module and provides the index or module code.

  • 2. Mod Manager deletes the module.

    Use case ends.

Extensions

  • 1a. The given index or module code is invalid.

    • 1a1. Mod Manager shows an error message.

      Use case resumes from step 1.

Appendix D: Non Functional Requirements

  1. The product should work on any mainstream OS as long as it has Java 11 or above installed.

  2. The product should be able to render its layout to different screen sizes.

  3. The product should be able to support up to 250 modules, 250 classes, 250 facilitators, and 250 tasks.

  4. The response to any command should become visible within 3 seconds.

  5. A user with above average typing speed for regular English text (i.e. not code and system admin commands) should be able to accomplish most of the tasks faster than doing the same task using the mouse.

  6. The product should work without any internet connection.

  7. The system failure rate should be less than 5 failure per 100 commands.

  8. Mod Manager’s internal storage can be transferred to other Mod Manager instances on other systems.

  9. The product should be intuitive and easy to use for a novice who has never used similar Task Management applications.

  10. A developer with one year of experience should be able to add a new feature, including source code modifications and testing, with no more than one week of labour.

  11. The product should not conflict with other applications or processes.

  12. The product is free and open source.

  13. The product is not required to handle non-NUS modules, or academic programmes at NUS not following a modular system.

  14. The product is not required to handle non-English characters for modules, classes, facilitators, and tasks' content.

Appendix F: Instructions for Manual Testing

Testing of General Features

  1. Launching the application.

    1. Download the jar file and copy into an empty folder. Double-click the jar file.
      Expected: Shows the GUI with a set of sample modules, classes, tasks and facilitators. The window size may not be optimum.

  2. Exiting the application.

    1. Type exit in the command box and press Enter.
      Expected: Closes the application window and saves data.

    2. Click on the close button on the application window.
      Expected: Similar to previous.

  3. Saving data.

    1. Delete the data file if it exists. Double-click the jar file.
      Expected: Shows the GUI with a set of sample modules, classes, tasks and facilitators.

    2. Edit the data file to contain duplicate modules. Double-click the jar file.
      Expected: Shows the GUI with an empty set of modules, classes, tasks and facilitators.

Testing of Module Feature

  1. Editing a module.

    1. Prerequisites: List all modules using the mod list command. Multiple modules in the list.

    2. Test case: mod edit 1 /desc SE
      Expected: Description of the first module in the list is updated to SE. Details of the edited module shown in the status message. Timestamp in the status bar is updated.

    3. Test case: mod edit 0
      Expected: No module is edited. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect mod edit commands to try: mod edit, mod edit x (where x is any value), mod edit x /desc SE (where x is negative, 0 or larger than the list size), mod edit 1 /code x (where a module with module code x exists)
      Expected: Similar to previous.