PROJECT: PlanMySem

Hello ! My name is Sean Yap and I am currently a Year 3 undergraduate and resident of Tembusu College at the National University of Singapore (NUS). This portfolio documents my contributions to PlanMySem, an application that was morphed from AddressBook Level 3 into a scheduling/calendar application that caters to NUS students and staff.

In summary, PlanMySem offers the following features:

  • Automatic creation of a planner that is synchronized to the NUS academic calendar for the current semester.

  • Quick and easy slot management (adding, editing and deleting of slots). This is achieved via two systems.

    • A unique recursion system which takes into account special weeks such as recess week or reading week to allow efficient adding of recurring items.

    • An intuitive tagging system to manage large amount of slots productively.

This application was developed as part of CS2113T, a software engineering module in the National University of Singapore (NUS), and consisted of 4 partners, Marcus, Julian, Ding Heng and myself; in which I served as the team lead. I was responsible for the slot management feature (add, edit and delete commands) and the structure of the codebase.

Overview

The next sections will illustrate these enhancements in more detail as well as the respective changes that I have made to both the user guide and developer guide.

Kindly take note that throughout this portfolio, there will be various icons used as described as such.

This is a tip. Follow these suggested tips to make your life much simpler when using PlanMySem!
This is a note. These are things for you to take note of when using PlanMySem.
This is a sign-post dictating important information. These are information that you will surely need to know to use PlanMySem efficiently.
This is a sign-post informing caution. Please take note of these items and exercise some care.

Summary of contributions

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

  • Main Feature: Slot management system, including the recursion and tagging system, of PlanMySem.

    • What it does: Slot management composes of the three interactions that users are able to perform regarding slots. As such, slot management consists of the execution of the add, edit and delete commands and its functions.

    • Justification: Slot management is the most crucial feature of PlanMySem, it is also the highlight of the application. Without so, the planner cannot be manipulated nor interacted with.

    • Highlights: This enhancement involved many variables and data types due to the nature of slots and its details. As such, this enhancement involved a large amount of cases, same was the came as with its tests. Additionally, to cater for greater user experience and ease of use, several variations of each functions were done up. For example, slots can be editing via tags or index.

  • Minor Features:

    • A new unique parsing system to replace the existing system for both prefixed parameters and keywords.

    • A clock system to manage dates and time more efficiently as with the nature of a planner application, the application is very time sensitive.

  • Code contributed:

    • View my RepoSense contribution analysis: [here]

    • View my Pull Requests: [here]

  • Other contributions:

    • Project Management: I was involved with the conception of PlanMySem and managed the codebase up till the release of version 1.4. These releases can be viewed here.

    • Testing: I wrote tests for all code in trying to achieve the most code coverage and ensure reliability of my code. Most of classes belonging to my features have 100% code coverage. At this time of writing, the code coverage for the entire codebase of PlanMySem is 91%.

    • Documentation: I updated the User Guide and Developer’s Guide regarding all items related to the features that I am in charge of and the design.

    • Community: I reviewed Pull Requests and provided non-trivial review comments for some requests. These Pull Requests can be viewed here.

    • Tools: Integrated all AddressBook Level 4 continuous Integration and continuous Deployment tools

      • Continuous Integration tools: Travis-CI, AppVeyor

      • Continuous Deployment tools: Netlify

      • Test Coverage History & Statistics tools: Coveralls

      • Automated code reviews and code analytics tools: Codacy

Contributions to the User Guide

This section shows some of my contributions to the User Guide. They not only showcase my ability to write documentation targeting end-users but also make user-centric design choices.

My contributions here can be summarised into 2 sections, features and adding, editing and deleting slots.

Features

Under the Features section, I contributed to explaining the Tagging and Recursion system that I designed.

Tagging System

Unlike other commercial calendar/scheduling/planner software, PlanMySem makes use of a tagging system to manage slots.

Using tags to tag slots will make tasks easier for you in the future. Performing tasks such as viewing, deleting and editing slots will be more efficient.

Recursion System

Recursion facilitates quick addition of multiple slots, similar to Microsoft Outlook’s series of appointments.

In NUS, academic semesters are split into weeks of several types. Recursion allows you to add slots to these types of weeks with ease through the use of the r/(recursion) parameter.

You can save time by utilizing the alternate and shortcut commands. E.g. instead of using delete, you may also use del or simply d.

Identifiers and Parameters

Identifiers in PlanMySem are designed to be, short and easy to memorise. Once you are familiarised with them, they should be intuitive to use to add your parameters. The table of Identifiers and Parameters and their descriptions (Table 1) below is useful for your reference as you jump right into grasping the system.

Table 1. Identifiers and their Parameters and descriptions.
Identifier Parameter Description Format Example

n/

NAME

Name of a slot

Text

n/CS2113T

KEYWORD

Text that are part of the name of a slot

Text

n/CS

l/

LOCATION

Location of a slot

Text

l/COM2 04-22

des/

DESCRIPTION

Description of a slot

Text

des/Topic: Abstraction

Further rows are omitted due to space constrains
You may order identifiers and parameters in any fashion and you will still be able to achieve what you want! So, do not bother thinking about where to place parameters as ordering does not matter, instead become more efficient and save your time!
Identifiers may be appended with a n to dictate "new".
E.g. nt/NEW_TAG signifies new tags in which you want to replace existing tags with.
While table 1 shows you all the identifiers and parameters that PlanMySem uses, there are some commands that do not make use of identifiers nor parameters. The view command is one such exception that make use of keywords that must be typed in a specific order.

Adding Slots : add / a

Here is an example of a helpful guide to a specific feature that I was responsible for.

Add slot(s) to the planner.
Format: add n/NAME d/DATE_OR_DAY_OF_WEEK st/START_TIME et/END_TIME_OR_DURATION
[l/LOCATION] [des/DESCRIPTION] [r/normal] [r/recess] [r/reading] [r/exam] [r/past] [t/TAG]…​

Examples:

  • add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture r/normal r/past
    Add a single slot, named "CS2113T Lecture" with description "Software Engineering" on all mondays, from 0800hrs to 0900hrs with the tags "CS2113T" and "Tutorial". Here, the recursion parameters enable a single command to place 13 slots on all "normal" weeks that lectures take place on.

Add Command Output 1
Figure 1. Output after entering add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture r/normal r/past

  • add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture r/recess r/reading r/past
    Do the same but instead of "normal" weeks, do the opposite of the norm and recurse the slot on both recess and reading week.

  • add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture
    Do the same but without any recursion, instead place the slot the coming monday.

You may add single slots by omitting the r/ identifiers and its parameters.
PlanMySem does not dictate your scheduling preferences. As such, you may even add identical slots or slots with overlapping start and end times to help plan for tentative/unconfirmed events.

Here, the editing and deleting slots features are omitted.

Contributions to the Developer Guide

This section shows some of my contributions to the Developer Guide.

They showcase my ability to:

  • Write technical documentation and create UML diagrams.

  • Design practical and effective code solutions.

  • Adhere to software engineering practices.

My contributions here can be summarised into 3 sections, design, slot management and Parser/Command Format and Structure.

Design

Under the design section, I wrote documentation and created UML diagrams to explain the overall system architecture. For instance, I documented the design of the architecture and its 4 innate components.

ArchitectureDiagram
Figure 2. Architecture Diagram

The Architecture Diagram given above explains the high-level design of the App. Given below is a quick overview of each component.

The .pptx files used to create diagrams in this document can be found in the diagrams folder. To update a diagram, modify the diagram in the pptx file, select the objects of the diagram, and choose Save as picture.

Main has only one class called Main. It is responsible for,

  • At app launch: Initializes the components in the correct sequence, and connects them up with each other.

  • At shut down: Shuts down the components and invokes cleanup method where necessary.

Common represents a collection of classes used by multiple other components.

The following class plays an important role at the architecture level, the App consists of four components:

  • UI: The UI of the App.

  • Logic: The command executor.

  • Model: Holds the data of the App in-memory.

  • Storage: Reads data from, and writes data to, the hard disk.

Each of the four components

  • Defines its API in an interface with the same name as the Component.

  • Exposes its functionality using a {Component Name}Manager class.

Logic component

LogicComponentClassDiagram
Figure 3. Structure of the Logic Component

API : Logic.java

The Logic component,

  1. uses the parser class to parse the user command.

    • This results in a Command object which is executed.

  2. The command execution can affect the Model (e.g. adding a Slot).

  3. The result of the command execution is encapsulated as a CommandResult object which is passed back to Ui.

  4. In addition, the CommandResult object can also instruct the Ui to display results, such as displaying help to the user.

Given below is the Sequence Diagram for interactions within the Logic component for the execute("delete 1") API call.

SDforDeleteSlot
Figure 4. Interactions Inside the Logic Component for the delete 1 Command

Here, the other 3 major components are omitted.

Slot Management

Slot Management involves mainly the interaction between the users and their slots.

The section below will describe in detail the Current Implementation, Design Considerations and Future Implementation of the Slot Management.

Current Implementation

Users are able to perform three actions (or commands), though a small variety of methods, involving slots:

  • Add

    • Add multiple slots via the recursion system.

    • Add a single slot via omitting the recursion system.

  • Edit

    • Edit multiple slots via tags.

    • Edit a single slot via index.

  • Delete

    • Delete slots via tags.

    • Delete a single slot via index.

The Add command heavily relies on the recursion system to select multiple dates in which to add the same slot to multiple days. Additionally, the Add command also allows users to input tags to tag slots.

The Edit and Delete command then makes use of the tagging system to then select multiple slots for editing/deleting.

Design Considerations

Here are the considerations regarding slot management. The choices made were largely due to computation effectiveness.

Aspect: Wrapping of data in Slot

The topic of whether to wrap all primitives and Strings, in Java, is contentious. However, in this case of PlanMySem, there are no possible invalid values for any of the data that Slot holds, other than the / character that would have already been handled by parser. For instance, any String is a valid name and the same goes for location, description and etc; wrapping these data will not achieve any narrowing of possible valid inputs.

Hence, data in Slot are not wrapped. This is in accordance to the You aren’t gonna need it (YAGNI) principle.

Aspect: Storing and accessing Slots

  • Alternative 1 (current implementation): Use of Map, such as HashMap to store Days that store Slots.

    • Pros: HashMap allows for easier and faster, O(1) access time, access of particular Day according to date.

    • Cons: This requires splitting of the calendar into days, as such there is no easy way to account for Slots that occur across days.

  • Alternative 2: Store Slots in a huge list.

    • Pros: Allows for easier access by "index" and offers flexibility, for example, in the time of slots.

    • Cons: Expensive to access, add and remove items. Furthermore, it is extremely expensive to collect slots that occur in a day, a very important and most likely to be a commonly used feature.

Alternative 1 was chosen as the benefits of quick and easy access to days outweigh the disadvantages involve with forbidding slots than span over a day. After all, there are few cases of slots crossing the boundaries of a day, over midnight.

Future Implementation

Create a class to represent Days, instead of utilising a HashMap

Currently, Days are held in a HashMap of key LocalDate and value Day. While this works without any loss in performance, this causes duplication of code and removes some key concepts of abstraction. For example, there are code blocks dedicated to retrieving days or slots that could have been placed into this new class. This is an issue as these code have nothing to do with for instance, Semester but they are placed there.

Therefore, this needs to be implemented in the future to achieve less coupling, more cohesion and respect the Single Responsibility Principle (SRP), Open-Closed Principle (OCP) and Separation of Concerns Principle (SoC).

Planner to hold multiple Semesters

While PlanMySem now allow users to work on the current semester, it is unable to cater to future semesters. For instance when a semester is about to end, users are not able to plan ahead for the coming semester.

This is an issue that plagues user experience and is a significant problem. To solve this issue, Planner needs to hold multiple semesters in a List and more features need to be included to allow saving, loading and switching of semesters and etc.

Parser / Command Format and Structure

Due to the flexibility and huge variation of the envisioned command format and structures, it was decided that it was more appropriate to create a new Parser instead of relying on the existing regex implementation in AB3 for heavy parsing.

The AB3 parser was heavily modified to serve unordered command parameters as well as to allow more flexibility such that mistakes in commands will still be interpreted as valid as long as the "minimal" set of parameters are present. Regex is currently only used to retrieve the command keywords and arguments. Arguments are then parsed via 2 different methods/techniques according to the format and structure of the command keyword.

Current Implementation

  • Ordering of parameters are ignored when possible.

  • Repeated parameters are ignored. The first parameter of the same "type" are taken as valid, the rest are discarded.

  • Alternate formats of commands are implemented to give freedom of choice and cater to different types of users such as different personalities and comfort levels.

  • Shortened versions of command keywords are implemented to give ways for users to shortened commands and be more efficient.

Hence, parameters in PlanMySem can be categorised into 2 categories:

  1. Prefixed parameters such as n/NAME, st/START_TIME, des/DESCRIPTION, etc.

  2. Non-Prefixed parameters, A.K.A. keywords, such as INDEX, TYPE_OF_VIEW. etc.

Parsing Prefixed Parameters

To retrieve parameters, the function private static HashMap<String, Set<String>> getParametersWithArguments(String args) can be called. The keys of the returned HashMap represent prefixes while the values represent the prefix’s parameters, held in a set. This allows for easy, quick and efficient access to specific prefixes and its parameters; O(1) access, insertion and removal.

The results of getParametersWithArguments can be interpreted in these manners:

  • When the returned set of parameters, to a specific prefix, is null, then both the prefix and parameters was not keyed in at all.

  • When the returned set of parameters, to a specific prefix, is not null but contains empty strings such that string.isEmpty() returns true, then the prefix was keyed in but the parameter was left blank.

The values of the returned HashMap is a Set, hence, there is no need to handle repeated parameters of a specific prefix as they will be automatically discarded.
Parsing Keywords

Here, keywords are thought of as parameters that are not prefixed. In PlanMySem, keywords are utilized in command structures when they are to be used alone or when order of parameters are important. In such cases, there is no logical need for prefixing as the meaning of these parameters can be identified.

The function private String getStartingArgument(String args) provides this functionality. Here, IncorrectCommand is invoked due to different circumstances:

  • When the keyword is null, then the parameter was not keyed in.

  • When the keyword data type does not match the intended, then the parameter was keyed in wrongly or is mis-ordered.

Additional keywords are purposefully not handled to provide ease of use and cater to user mistakes.

Here, the design considerations and future implementations are omitted.