PROJECT: Deadline Manager

This portfolio serves to document my contribution in a Software Engineering team project for CS2103T. The team comprises of 5 members and we were tasked to develop a working application within 6 weeks.

To comply with the module requirements, the team is constrained to start from an existing code base - AddressBook Level 4 and the user must interact with the application via Command Line Interface (CLI). The final product that my team has developed is Deadline Manager, which will be detailed below.

1. Overview

Deadline Manager is an application that allows users to easily manage their tasks and deadlines. It enables users to keep track of and focus on important activities.

For more information, the Github page with the full source can be found: [on GitHub].

2. Summary of Contributions

  • Major enhancement: added the ability to manage attachments of tasks in Deadline Manager

    • What it does: It allows users to add, list, delete or retrieve (get) attachments from any task added to the Deadline Manager. Users that want to associate certain files to a particular task can do so via this Attachment feature.

    • Justification: Tasks usually come with associated files that are required when a user performs the task. With this feature, users will be able to categorize and organize files related to tasks. This will reduce the time required for the user to search for these files at a subsequent stage, thereby increasing effectiveness in completing tasks.

    • Highlights: This enhancement requires interaction with the user’s filesystem. As users can run Deadline Manager with different Operating Systems, the filesystem in each Operating System behaves slightly differently. As a result, intensive testing and careful coding was required in order to ensure that the feature works on various Operating Systems.

  • Minor enhancement: modified the User Interface (UI) to be task-centric

    • What was modified:

      • Removed UI elements from the original AddressBook that were not relevant to Deadline Manager.

      • Added UI elements that displayed attributes of Tasks that are relevant to Deadline Manager. Example: displaying priority, deadline and the labels of attachments of a task.

  • Code contributed: [Commits]

  • Other contributions:

    • Project management:

      • Managed release v1.1 on GitHub

      • Contributed to 11 user stories on GitHub Issue Tracker (User Stories)

      • Reported bugs in Deadline Manager: #149, #178, #179

      • Reviewed Pull Requests (with non-trivial review comments): #143, #154, #112

      • Integrated AppVeyor and Coveralls to the team repository.

    • Significant modification of Address Book’s code base for use in Deadline Manager:

      • Rename Address Book application to Deadline Manager (#31)

      • Remove unnecessary fields from User Interface (#92)

      • Renaming of class and variable names (#126)

3. Contributions to the User Guide

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

3.1. Managing attachments of a task : attachment

Allows the user to add, list, delete and retrieve files associated with a specific task.
Deadline manager does not make a copy or backup the files added. Only the location of the files are stored by Deadline Manager. Hence, it is possible that the file might have been modified, renamed, moved or deleted without Deadline Manager’s knowledge. As such, there is no guarantee for a file associated with a specific task to always exist.
After the command is successfully executed, all the tasks in Deadline Manager will be listed.
Format (in general): INDEX ACTION [p/"FILEPATH"] [n/"FILENAME"]

More specific formats for each actions are listed below.

  • Format for Add Actions: attachment INDEX add p/"FILEPATH"

  • Format for Delete Actions: attachment INDEX delete n/"FILENAME"

  • Format for List Actions: attachment INDEX list

  • Format for Get Actions: attachment INDEX get n/"FILENAME" p/"FILEPATH"

    The application does not allow adding more than one file with the same filename to the same task, even if they are in different locations on the computer. For this application, filename includes the file extension as well.

  • Modify and manages the attachments of the task at the specified INDEX. The index refers to the index number shown in the displayed task list. The index must be a positive integer 1, 2, 3, …​

  • ACTION is either add, list, delete or get

  • For add actions, the FILEPATH argument is required to denote the file you intend to attach to the task. A file must exist at the FILEPATH specified. The FILEPATH must be enclosed in quotation marks. For example: "D:/Documents/HelloWorld.txt"

  • For list actions, no additional arguments are required.

  • For delete actions, the FILENAME argument is required to represent the file to delete. The FILENAME must be enclosed in quotation marks. For example: "Hello World.docx".

  • For get actions, the FILENAME argument is required to represent the file to retrieve and the FILEPATH argument is required to denote the destination you want the file to be exported to. If there is an existing file at FILEPATH, it would be overwritten without warning. The FILEPATH and FILENAME must be enclosed in quotation marks, similar to the arguments in add and delete actions. Do note that FILEPATH should be a path to a file, not a folder in the computer.

To avoid ambiguity, it is recommended to use quotation marks when specifying a FILEPATH or FILENAME. Those that are not enclosed in quotations will still be parsed. However, the correct behaviour is not guaranteed.
If your filename contains double quotation marks " but not single quotation marks ', you may enclose the filename with single quotation marks ' instead. However, the application will not be able to work with files that have both double quotation marks and single quotation marks.

Examples:

  • Add: attachment 1 add p/"D:\Documents\Hello World.docx"
    Adds an attachment located at "D:\Documents\Hello World.docx" to the 1st task currently listed in the deadline manager. (Tip: You can list all tasks using the list command.)

AttachmentDemo2
Figure 3.8.1: Result of Attachment Command with Add Action

Figure 3.8.1 above shows an expected result message if the command is successfully executed by Deadline Manager for the example command.

AttachmentDemo2
Figure 3.8.2: Attachment Label after an attachment is added to a file

Figure 3.8.2 above shows the label that would be displayed along with the task after an attachment is added. The label will contain the file name.

  • List: attachment 1 list
    Lists all attachments currently associated with the 1st task in the deadline manager.

AttachmentDemo3
Figure 3.8.3: Result of Attachment Command with List Action

Figure 3.8.3 above shows an expected result message if the command is successfully executed by Deadline Manager for the above command with the List Action.

The description for Delete and Get actions are omitted. For the full text, please refer to the User Guide.

Below is a segment that I contributed to the Frequently Asked Question (FAQ) section of the User Guide.

Q: How do I obtain the FILEPATH of a particular file in my Computer?
A: For Windows 10 users, you may follow the following steps using the File Explorer application on your Computer in order to obtain the FILEPATH:

  1. Navigate to the file you intend to obtain the FILEPATH of using the File Explorer application.

  2. Select the file which you intend to obtain the FILEPATH of.

  3. Click on Home near the top left corner of the File Explorer application.

  4. Click on the Copy path button as indicated in Figure 4.1 below. The FILEPATH will then be copied onto your clipboard.

  5. Go to the command box of Deadline Manager and paste the FILEPATH as required.

QnAFilepath1
Figure 4.1: Copy path button within the File Explorer application

Figure 4.1 above indicates which button should be clicked in order to obtain the FILEPATH. The FILEPATH should look something similar to "D:\Documents\123 p\Assignment.docx". You can use this for the FILEPATH argument in both import, export and attachments.

4. Contributions to the Developer Guide

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

4.1. Attachment feature

The attachment feature aims to help users organise and keep track of important files needed for the respective tasks. It allows users to associate files in their computer with a particular task. When the user subsequently decides to perform a particular task, this feature provides functionality to identify files previously associated with the task and facilitates exporting it to an appropriate location.

4.1.1. Current implementation

The attachment feature is mainly implemented by AttachmentCommand. As AttachmentCommand is an all-purpose command involving numerous actions, an interface AttachmentAction is defined within AttachmentCommand in order to facilitate this. There are 4 classes that implements AttachmentAction in order to implement the various actions of the attachment feature. The command line arguments for the attachment command is parsed by AttachmentCommandParser.

4.1.2. Sequence flow

Given below is just one example of a sequence flow that was documented in the Developer Guide.

Given below is another sequence of steps, also illustrated by the sequence diagram. They describe the interaction between AttachmentCommand and classes that implement AttachmentAction after the AttachmentCommand#execute method is invoked by the LogicManager.

AttachmentExecuteSequenceDiagram
Figure 1. Sequence Diagram for performing the execute method of an AttachmentCommand.

Step 1. The task identified by the user is retrieved from the Model.

Step 2. The perform method of the AttachmentAction is invoked, with the task retrieved in Step 1 as the parameter.

Step 3. The invoked AttachmentAction performs specific application logic which is different for each action. Then, a ActionResult object containing a Task and a message is returned to the execute method.

Step 4. The Model is updated with the Task object retrieved from the returned ActionResult.

Step 5. The message to be shown to the user is retrieved from the returned ActionResult. Then, it is used to create a CommandResult object which is to be returned to the the LogicManager.

4.1.3. AttachmentAction and implementing classes

AttachmentAction is an interface nested within AttachmentCommand. It defines and requires implementing classes to implement a perform method. The implementation for AttachmentAction is shown below:

public interface AttachmentAction {

    ActionResult perform(Task taskToEdit) throws CommandException;

}

  • The perform method is invoked by AttachmentCommand to perform the action on the task provided. ActionResult is immutable and contains two properties: a Task and a message which can be used by implementing classes to return the updated Task together with any message that should be displayed to the user. Since Task is immutable, a new task with the modified values should be returned by the method, instead of modifying taskToEdit.

The contents of ActionResult is shown below:

private static class ActionResult {
    public final String resultMessage;
    public final Task updatedTask;

    public ActionResult(Task updatedTask, String resultMessage) {
        this.updatedTask = updatedTask;
        this.resultMessage = resultMessage;
    }

    // Returns the task
    public Task getTask() { return updatedTask; }

    // Returns the result message
    public String getMessage() { return resultMessage; }
}
4.1.3.1. AddAttachmentAction

AddAttachmentAction implements AttachmentAction and provides the implementations required for the user to associate a file with a task. In other words, it adds an attachment to a task. The constructor class takes in a single parameter, filePath, denoting the path to the file to be associated with the task. The perform method of AddAttachmentAction executes the following:

  1. Checks if a file exists at the specified filePath. A CommandException will be raised if this is not the case.

  2. Checks if the task already contains an attachment with the same filename. A CommandException will be raised if this is not the case.

  3. Constructs a new Attachment object using the file at the specified filePath.

  4. Constructs a new Task object with the same attributes as the original task, but with the additional Attachment object added to the set of attachments.

4.1.3.2. ListAttachmentAction

ListAttachmentAction implements AttachmentAction and provides the implementations required for the user to list all the files associated with a task. In other words, it provides a listing of all attachments that are added to the task. The constructor class requries no parameters. The perform method of ListAttachmentAction executes the following:

  1. Prints the total number of attachments in the specified task.

  2. Prints the filename of each of the attachments in the specified task, with one attachment per line.

Description for DeleteAttachmentAction and GetAttachmentAction are omitted for brevity.

4.1.4. Design considerations

4.1.4.1. Aspect: How to associate files to tasks

  • Alternative 1 (current choice): Saves the path of the file.

    • Pros: Easy to implement. Reduces storage footprint.

    • Cons: Associated file can cease to exist, due to it being renamed, moved or deleted.

  • Alternative 2: Copies the entire file to a user specified directory.

    • Pros: Deletion of the associated file (in its original location) will not affect the application.

    • Cons: Harder to implement file management system on the file system. Uses more storage space. User will not be able to update the attachment without deleting and re-adding the file.

4.1.4.2. Aspect: How to identify attachments within a task

  • Alternative 1 (current choice): Use the file name as an identifier.

    • Pros: More user friendly as there is less words to type.

    • Cons: Cannot have more than one attachment with the same file name in the same task. For example: folder1/Template.docx and folder2/Template.docx cannot be simultaneously added as attachments to the same task.

  • Alternative 2: Use the path to the file as an identifier.

    • Pros: Allows for more than one attachments with the same file name to be associated with the same task. For example: folder1/Template.docx and folder2/Template.docx can be added to the same task as attachments.

    • Cons: Cumbersome for the user to type the full path to identify the file.

  • Alternative 3: Prompt the user for an identifier for each attachment added.

    • Pros: Can be customized by the user to manage multiple files with the same file name in the same task.

    • Cons: Cumbersome for the user to type the identifier for every time they want to add attachments to a task.

For the full content of the Attachment section, please do refer to the Developer Guide.