PROJECT: PlanWithEase

Hi! I am Ahn Tae Gyu, an Information Security student in National University of Singapore. I am keen on writing programs that help to improve qualities of our lives. You will be able to find brief introduction of the project along with some of my contributions to the project below.

Overview

PlanWithEase (PWE) is a degree planner desktop application designed to help National University of Singapore (NUS) Information Security freshmen in creating a comprehensive degree plan according to the degree requirements. PWE is designed to be simple and intuitive application that allows users to interact with by typing the commands (using a Command Line Interface). Moreover, PWE also comes with a clean Graphical User Interface (GUI) that presents information in an organized manner.Hence, even if you are unfamiliar with the Command Line Interface, you will not need to spend much time understanding how to use PWE. PWE was completed by a team of five members consisting of Ngo Wei Lin, Bai YunWei, Lee Yu Choy, Yeo Cheng Hong and me.

Ui

Understanding This Project Portfolio

The following symbols are used throughout this project portfolio:

This symbol denotes information that you may want to take note of when using the application.

This symbol denotes a tip which you may find useful when using the application.

This symbol denotes a warning message which you need to be careful of when using the application.

Additionally, you may also encounter the following text styles:

  • Commands or parameters will be in this format.

  • Important messages will be bold.

  • Undoable command will be in italics.

  • Keyboard buttons will be referred to as such: F1.

Summary of contributions

Given below is a summary of contributions I made in this project.

Major Enhancement: Degree Plan Management

Planner Move, Planner Show & Planner list

During this enhancement, Degree Planner model was build to allow other developer Bai YunWei and me to integrate planner related features into the application as well as stores degree plan related information.

  • Summary of the features:

    • Planner Move feature allows a module in the degree plan to be easily moved to another semester.

    • Planner Show feature allows displaying of specific semesters.

    • Planner list feature allows displaying of all semesters in the degree plan.

  • Justification:

    • Users can keep track of degree plan details (such as modules to take in particular semesters).

    • Users can easily make changes to the degree plan by moving a module in the degree plan with planner_move command.

    • Users can easily display specific semesters that the user wants with planner_show command.

  • Highlights:

    • During the enhancement, there were numerous reviews done to ensure that no other model components is broken and any degree plan related features can be integrated without any problem.

  • Planner Move was enhanced to carried out checks for the module’s co-requisite and semesters it and its co-requisites are offered in.

  • Planner Show was enhanced to utilize boolean expression parser that was designed by Lee Yu Choy.

  • Credits:

    • Plenty of module corrections and suggestions were made during the built of Degree Planner model by Ngo Wei Lin.

    • Boolean expression parser was designed by Lee Yu Choy.

Minor Enhancement: Adding UI segment for degree plan

  • Justification: UI part for degree plan was added to displays the semesters and modules to be taken during the semesters.

  • Highlights:

    • Browser Panel that existed originally have to be adjusted in order for the UI part of the degree plan to be added.

    • UI for Degree plan was updated to sort the degree plan before displaying.

  • Credits:

    • Beautification of the overall UI including the part for the degree plan was done by Lee Yu Choy

Code Contributed:

Commits, Pull Requests & RepoSense Code Contribution Dashboard

Other contributions:

  • Project management:

  • Enhancements to existing features:

    • Enhance planner_move feature to handle co-requisites as well as semester the modules are offered in (Pull Request #197)

    • Enhance planner_show feature to utilize BooleanExpressionParser (Pull Request #196) (Note: this was done during the implementation)

  • Documentation:

    • Update UI mock up for

      • v 1.1 (Pull Request #31)

      • v.1.2 (Pull Request #98)

    • Manage user guide (e.g. Pull Request #47)

    • Manage developer guide (e.g. Pull Request #2, #7)

    • Documentation management was mainly done through reviews (e.g. #172)

  • PRs reviewed: Approved Pull Requests

  • Issues:

    • Opened issues for enhancement and improvements that could be made (e.g. 164, 97)

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.

Moving a module between semesters: planner_move planner move F17D3F

Any change in your decision? Want to take your module in other semester instead?
No worry! Simply use planner_move command to move your module in the degree plan along with its co-requisite(s) between the semesters by providing your module code and a semester you want to move your module to.

Command Format: planner_move year/YEAR sem/SEMESTER code/CODE

When moving a module with co-requisites, if the module is moved successfully, the co-requisite modules will be moved as well.

Examples:

  • planner_move year/1 sem/2 code/CS1231
    Moves module CS1231 along with its co-requisite(s) to year 1 semester 2.

  • planner_move year/2 sem/1 code/CS1231
    Moves module CS1231 along with its co-requisite(s) to year 2 semester 1.

Before the planner_move command:

plannermove1
Figure 1. Before executing the planner_move command.

After entering planner_move and pressing Enter:

plannermove2
Figure 2. After executing the planner_move command.

Note that co-requste of the module is moved too:

plannermove3
Figure 3. After executing the planner_move command.

Showing semesters based on year/semester: planner_show planner show F17D3F

Having trouble locating semesters you want?
Simply use planner_show command. It will only show you the semesters you want to see.

Command Format: planner_list [y/YEAR] OPERATOR [s/SEMESTER]

When this command is used, the application will display only those semesters which satisfy the search criteria.

The following table describes the valid prefixes that you can use to supply to the search criteria.

Prefix

Description

year/YEAR

Search for any semester year which matches YEAR

sem/SEMESTER

Search for any semester sem which matches SEMESTER

The following table describes the valid operators which you can to use supply to the search criteria.

Operator

Description

Precedence

&&

Logical "AND" operation (both conditions A AND B must match)

Highest

||

Logical "OR" operation (either conditions A OR B must match)

Lowest

The following examples describes how you could form a valid search criteria for the planner_show command.

Single Prefix Usage

Expected Result

planner_show year/YEAR

Shows only semesters that are in year YEAR

planner_show sem/SEMESTER

Shows only semesters that are in semester SEMESTER

If you need multiple prefixes, the following table shows you how you could do it.
Note that you will need to separate multiple prefixes with an operator.

You could choose which search criteria having a higher priority by specifying parenthesis

Multiple Prefix Usage

Expected Result

planner_show year/YEAR1 || year/YEAR2

Shows only semesters that are in years YEAR1 or YEAR2.

planner_show sem/SEMESTER1 || sem/SEMESTER2

Shows only semesters that are in semester SEMESTER1 or SEMESTER.

planner_show sem/SEMESTER && (year/YEAR1 || year/YEAR2)

Shows only semesters that are in year YEAR1 semester SEMESTER or YEAR2 semester SEMESTER.

  • The order of the prefixes does not matter. e.g. planner_show sem/SEMESTER || year/YEAR returns the same result as planner_show year/YEAR || sem/SEMESTER

Examples:

  • planner_show year/1
    Shows any semesters having the year 1 (e.g. Year 1 Semester 1, Year 1 Semester 2 …​) in the degree plan.

  • planner_show sem/1
    Shows any semesters having the year 1 (e.g. Year 1 Semester 1, Year 2 Semester 1 …​) in the degree plan.

  • planner_show year/1 || year/2
    Shows any semesters having the year 1 or year 2 in the degree plan.

  • planner_show sem/1 || sem/2
    Shows any semesters having the semester 1 or semester 2 in the degree plan.

  • planner_show year/1 && sem/1
    Shows a semester having the year 1 and semester 1 (e.g. Year 1 Semester 1)in the degree plan.

  • planner_show sem/1 && (year/1 || year/2)
    Shows a semester having the year 1 semester 1 and year 2 semester 1 (e.g. Year 1 Semester 1 and Year 2 Semester 2) in the degree plan.

Before the planner_show command:

plannershow1
Figure 4. Before executing the planner_show command.

After entering planner_show and pressing Enter:

plannershow2
Figure 5. After executing the planner_show command.

Listing all semesters: planner_list planner list F17D3F

Maybe you need to list all your semesters back after using planner_show?
Simply enter planner_list into the application!
It wil show you a list of all semesters in degree plan.

Command Format: planner_list

Using degree plan to suggest modules : planner_suggest planner suggest F17D3F

Having trouble identifying modules to add to the degree plan?
Make use of planner_suggest command to find out recommended modules to add to the degree plan.

Command Format: planner_suggest credits/CREDITS [tag/TAG]…

When this command is successfully executed, the result box will display modules recommended.

  • Maximum 10 modules are recommended in the recommendation list.

  • In addition to the recommendation list, supplementary information on the specific modules with matching tags and credits is given as two additional lists. The modules in the two additional lists are all from the recommendation list.

  • Modules recommended in all 3 aforementioned lists are sorted according to the following criteria:

    • For modules with different number of tags that match the desirable tags (matching tags), modules with more matching tags will be sorted to the front of the list.

    • If modules have the same number of matching tags but different credits, modules with the credits closer to the desirable credits will be sorted to the front of the list.

    • If modules have the same number of matching tags and credits, they will be sorted according to alphabetical order.

    • If tag/TAG is not supplied as a parameter in the command, modules will be sorted according to credits and alphabetical order only.

  • All modules in the recommendation list and the two additional lists are modules not found in the degree plan.

Examples:

  • planner_suggest credits/4
    Suggests maximum 10 modules not found in the degree plan, prioritizing modules with credits closer to 4. If tie, prioritizes according to alphabetical order.

  • planner_suggest credits/2 tag/algorithms
    Suggests maximum 10 modules not found in the degree plan, prioritizing modules with tag algorithms. If tie, prioritizes according to credits closer to 2. If tie again, prioritizes according to alphabetical order.

Future Enhancements [coming in v2.0]

These are features that will come in future releases of PlanWithEase

Module Prerequisites prereq/

We aim to provide the support of prerequisites for our Module Management.
This changes will allow our users to indicate a module prerequisites and we can handle its dependency for the users before they add the module into the Degree Plan.

Auto-create Degree Plan autoplan

We plan to implement this feature to allow an automated planning, we can make use of users feedback and current treads based on module popularity then create the degree plan for the users.

FAQ

Q: How do I save my data in the application?
A: You do need to save the data manually. Whenever you run any commands that makes changes, PlanWithEase's data are saved automatically in the data directory.

Command Summary

This section provides a quick references for all commands available in PlanWithEase.

General Commands

The table below shows a list of general commands.

Task

Purpose

Command Format

Example

Help

Displays the User Guide

help

help

History

Get a list of command entered

history

history

Undo

Undo your previous action

undo

undo

Redo

Redo your previous action

redo

redo

Clear

Clear the all the modules from the specified section

clear [requirement or planner]

clear

Reset

Resets and populates the application with sample data

reset

reset

Exit

Exits the application

exit

exit

Module Management Commands

The table below shows a list of commands which helps you to manage the module list.

Task

Purpose

Command Format

Example

Add module to module list

Add a new module to the module list.

add code/CODE name/NAME credits/CREDITS [sem/SEMESTER]… [coreq/COREQUISITE]… [tag/TAG]…

add code/GEH1074 name/Luck credits/4 sem/1 sem/2

Edit the details of a module

Edit the module’s details based on the index given.

edit INDEX [name/NAME] [code/CODE] [credits/CREDITS] [sem/SEMESTER]… [coreq/COREQUISITE]… [tag/TAG]…

edit 1 name/Data Structures and Algorithms code/CS2040C

Delete module from module list

Remove the module entirely from the module list based on the index given.

delete INDEX

delete 3

Find modules in the module list

Display a list of modules based on your search criteria

find [name/NAME] OPERATOR [code/CODE] OPERATOR [credits/CREDITS] OPERATOR [sem/SEMESTER] OPERATOR [tag/TAG]

find credits/4 && (name/Programming || name/Discrete)

List all modules

List all modules available in the module list

list

list

Selecting a module

Selects a module in the module list

select INDEX

select 1

Requirement Tracker Commands

The table below shows a list of command which helps you to manage and track your degree requirements.

Task

Purpose

Command Format

Example

Add module(s) to a requirement category

Add module(s) to the specified requirement category based on the module code provided.

requirement_add name/NAME code/CODE [code/CODE]…

requirement_add name/IT Professionalism code/IS4231

Remove module(s) from the requirement category

Remove module(s) from the requirement category based on the module code provided.

requirement_remove code/CODE [code/CODE]…

requirement_remove code/IS4231

Move module(s) between requirement categories

Move module(s) between the requirement categories from any requirement categories to a specified requirement categories.

requirement_move name/NAME code/CODE [code/CODE]…

requirement_move name/IT Professionalism code/IS4231

List all requirement categories in the application

List all requirement categories in the application and the module(s) added to each requirement categories

requirement_list

requirement_list

Degree Plan Commands

The table below shows a list of commands which helps you to manage the degree plan.

Task

Purpose

Command Format

Example

Add module(s) to degree plan

Add module(s) to degree plan based on module code and academic year

planner_add year/YEAR sem/SEMESTER code/CODE [code/CODE]…

planner_add year/1 sem/2 code/CS1010 code/CS2113T

Remove module(s) from degree plan

Remove module(s) from degree plan based on the module code

planner_remove code/CODE [code/CODE]…

planner_remove code/CS1231 code/CS1010

Move module between semesters in the degree plan

Move module between the semesters based on year and semester.

planner_move year/YEAR sem/SEMESTER code/CODE

planner_move year/1 sem/2 code/CS1231

List all semesters in the degree plan

List all semesters in the degree plan

planner_list

planner_list

List specific semesters in the degree plan

List specific semesters in the degree plan based on your search term.

planner_show [year/YEAR] OPERATOR [sem/SEMESTER]

planner_show sem/2 && ( year/1 ||year/2 )

Suggest available modules

Suggest available modules from the module lists based on input argument.

planner_suggest credits/CREDITS [tag/TAG]…

planner_suggest credits/4 tag/maths

Showing semesters based on year/semester: planner_show planner show F17D3F

Having trouble locating semesters you want?
Simply use planner_show command. It will only show you the semesters you want to see.

Command Format: planner_list [y/YEAR] OPERATOR [s/SEMESTER]

When this command is used, the application will display only those semesters which satisfy the search criteria.

The following table describes the valid prefixes that you can use to supply to the search criteria.

Prefix

Description

year/YEAR

Search for any semester year which matches YEAR

sem/SEMESTER

Search for any semester sem which matches SEMESTER

The following table describes the valid operators which you can to use supply to the search criteria.

Operator

Description

Precedence

&&

Logical "AND" operation (both conditions A AND B must match)

Highest

||

Logical "OR" operation (either conditions A OR B must match)

Lowest

The following examples describes how you could form a valid search criteria for the planner_show command.

Single Prefix Usage

Expected Result

planner_show year/YEAR

Shows only semesters that are in year YEAR

planner_show sem/SEMESTER

Shows only semesters that are in semester SEMESTER

If you need multiple prefixes, the following table shows you how you could do it.
Note that you will need to separate multiple prefixes with an operator.

You could choose which search criteria having a higher priority by specifying parenthesis

Multiple Prefix Usage

Expected Result

planner_show year/YEAR1 || year/YEAR2

Shows only semesters that are in years YEAR1 or YEAR2.

planner_show sem/SEMESTER1 || sem/SEMESTER2

Shows only semesters that are in semester SEMESTER1 or SEMESTER.

planner_show sem/SEMESTER && (year/YEAR1 || year/YEAR2)

Shows only semesters that are in year YEAR1 semester SEMESTER or YEAR2 semester SEMESTER.

  • The order of the prefixes does not matter. e.g. planner_show sem/SEMESTER || year/YEAR returns the same result as planner_show year/YEAR || sem/SEMESTER

Examples:

  • planner_show year/1
    Shows any semesters having the year 1 (e.g. Year 1 Semester 1, Year 1 Semester 2 …​) in the degree plan.

  • planner_show sem/1
    Shows any semesters having the year 1 (e.g. Year 1 Semester 1, Year 2 Semester 1 …​) in the degree plan.

  • planner_show year/1 || year/2
    Shows any semesters having the year 1 or year 2 in the degree plan.

  • planner_show sem/1 || sem/2
    Shows any semesters having the semester 1 or semester 2 in the degree plan.

  • planner_show year/1 && sem/1
    Shows a semester having the year 1 and semester 1 (e.g. Year 1 Semester 1)in the degree plan.

  • planner_show sem/1 && (year/1 || year/2)
    Shows a semester having the year 1 semester 1 and year 2 semester 1 (e.g. Year 1 Semester 1 and Year 2 Semester 2) in the degree plan.

Before the planner_show command:

plannershow1
Figure 6. Before executing the planner_show command.

After entering planner_show and pressing Enter:

plannershow2
Figure 7. After executing the planner_show command.

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.

Planner Move Feature

The planner_move command aims to provide functionality for users to move a module between academic semesters in the degree plan along with its co-requisites.

This section shares the implementation and design considerations made during the enhancement of the planner_move feature.

Overview

As the users often encounter situations where they decide to take the modules in other semesters after they have completed their degree planning, the planner_move feature is essential to have.

Current planner_move feature supports the moving of a module along with its co-requisites given the module and its co-requisites are offered in the semester the users wants to move to.

Current Implementation

When a user execute the planner_move command (e.g. planner_move year/1 sem/2 code/CS1010), the following steps are taken by the application.

Given below is a sequence diagram for moving a module that illustrates the interactions among PlannerMoveCommand, PlannerMoveCommandParser and Model:

PlannerMoveComponentSequenceDiagram
Figure 8. PlannerMove component interactions

Step 1. The PlannerMoveCommandParser#parse method is invoked. The PlannerMoveCommandParser receives the command with the arguments as a string.

Step 2. The PlannerMoveCommandParser parses the text related to each PREFIX and constructs the PlannerMoveCommand . If more than one of each kind of PREFIX (e.g. year/1 sem/2 code/CS1231 code/CS1010) is provided, only text related to last of each PREFIX (e.g. year/1 sem/2 code/CS1010) will be parsed.

  • The input should consist of the year and the semester of the degree plan that the user wants to move to and the module code that the user want to move.

  • PlannerMoveCommandParser will throw an error if the user input does not match the command format.

Step 3. The PlannerMoveCommand with YEAR, SEMESTER and CODE specified by the user is returned.

Step 4. The PlannerMoveCommand#execute method is invoked.

Given below is a sequence diagram that illustrates the interactions among PlannerMoveCommand, Model and Application:

PlannerMoveCommandSequenceDiagramDetail
Figure 9. PlannerMoveCommand in detail interactions

During this step, the following methods are carried out in the order:

  • The getDegreePlannerByCode method will be called to check if there exists any academic semester in degree plan that has the parsed module code.

  • The getApplication method will be called followed by the getDegreePlannerList method will be called by the model to retrieve the list of academic semesters available in the degree plan. Then, filter will be carried out with the help of DegreePlanner#isSameDegreePlanner to locate the academic semester the user wants to move the module to.

null will be returned instead of DegreePlanner object if no academic semester matching the year and the semester is found.

  • The getModuleByCode method will be called to return Module object having the code toMove. Then, the Module object will be used to retrieve the semesters the module is available in with the getSemesters method to check if the module is offered in the academic semester the user is trying to move to.

  • The getModuleByCode method will be called in a loop during the filter to find out all the module’s co-requisites not offered in the academic semester the user is trying to move to.

Any violations in the checks will result in throwing of an error message.

Step 5. The Model is updated.

  • If any of the above check fails, Model will not be updated since there is nothing to be changed.

  • If all the above checks passes, the PlannerMoveCommand class will update the context in ModelManager by calling the`moveModuleBetweenPlanner` method which will call setDegreePlanner method.

  • After updating the Model The PlannerMoveCommand will save the current database state through commitApplication (for undo/redo functions).

Step 6. A CommandResult object is returned.

Design Considerations

Aspect: How should searching of the degree plan based on the year and the semester provided to be done

  • Alternative 1 (current choice): Construct DegreePlanner object with the year and the semester provided and use DegreePlanner#isSameDegreePlanner to compare and search for the corresponding degree plan.

Pros

There is no need to create any method that may create unnecessary coupling.

Cons

There is a need to create a DegreePlanner object in order to use DegreePlanner#isSameDegreePlanner.

  • Alternative 2: Create getDegreePlanner method which retrieves DegreePlanner object based on the year and the semester provided.

Pros

Easy to implement.

Cons

The method will create unnecessary couplings between Application and Year as well as between Application and Semester.

Planner Show Feature

Planner show feature aims to help users to be able to easily locate and display any academic semesters in the degree plan which is in our application. We support the displaying of degree planners based on year, semester and boolean expressions. This enables our users to display only specific academic semesters in the degree plan that they want.

Overview

When a user invokes the planner_show command. (e.g. planner_show y/YEAR && s/SEMESTER), the following steps are taken by the program.

  1. Extract the text related to planner_show command (e.g. y/YEAR && s/SEMESTER)

  2. Parse the text related to each PREFIX individually.

  3. Return a composite predicate for all attributes.

Step 1 is performed by the ApplicationParser class.

Step 2 and 3 are performed by BooleanExpressionParser#parse.

Current Implementation

  • Show degree planner(s) by year i.e. planner_show y/YEAR returns degree planner(s) having its year matches the year given

  • Show degree planner(s) by semester i.e. planner_show s/SEMESTER returns degree planner(s) having its semester matches the semester given

  • include year and semester attributes in one planner_show command and list degree planner(s) i.e. planner_show y/YEAR s/SEMESTER returns module having its year or semester matches the given year and semester

Design Considerations

Aspect: How to parse multiple attributes

  • Alternative 1 (current choice): Parse the text related to each PREFIX individually using BooleanExpressionParser

Pros

User is able to have more flexible search.

Cons

More time and work needed for developer to implement.

  • Alternative 2: Parse the text related to each PREFIX at one go without using BooleanExpressionParser

Pros

Easy to implement.

Cons

Additional overhead needed and inconsistent in the application’s commands since find utilises BooleanExpressionParser.