PROJECT: GradTrak

Overview

My team was tasked with enhancing a basic command line interface (CLI) AddressBook for our Software Engineering project. We decided to morph it into a school module tracker called GradTrak.
GradTrak is an application designed for students of National University of Singapore (NUS) to easily plan and track modules as well as check them against the graduation requirements.
The user interacts with GradTrak mainly through the CLI, but it also has a Graphical User Interface (GUI) created with JavaFX. It is written in Java and has more than ten thousand lines of code.

My role was to design and write the codes for the module recommendation feature, and to enhance the existing module finding feature. The following sections illustrate these contributions in more detail, as well as the relevant sections I have added to the User Guide and Developer Guide.

Summary of contributions

This section summarises my coding and other helpful contributions to GradTrak.

  • Major enhancement: added a module recommendation feature

    • What it does: This feature displays a list of modules which the user is recommended to read based on existing GradTrak modules and graduation requirements specific to the user’s course of study. The list is sorted primarily by the priority of the requirement type satisfied by the recommended module, and secondarily by the level of the module.

    • Justification: This feature significantly benefits users who are unfamiliar with the exact graduation requirements of their course, or are unsure of what modules to read for future semesters. They can simply pick a high-priority module near the top of the recommendation list — this module already has its prerequisites satisfied, contributes to their graduation requirements and will likely serve as a prerequisite for higher level modules. This allows users to plan their modules systematically so that they are on the right track towards graduation.

    • Highlights: The implementation of this feature was challenging as it requires interactions with many components of GradTrak. It needs to retrieve information of all NUS modules, check each module for its preclusions or prerequisites in the user’s module list, and determine whether it contributes to the user’s course requirements and if so, the requirement type of highest priority that it satisfies. In particular, it was necessary to liaise with the implementation of the graduation-checking feature to ensure that the recommended modules actually bring the user closer to graduation.

  • Minor enhancement: added additional parameters for the module finding feature, allowing the user to search GradTrak modules by module code, semester, grade or finished status.

  • Code contributed: [Project Code Dashboard]

  • Other contributions:

    • Project management:

      • Managed release v1.3 on Github (releases)

      • Added user stories on Github (example)

    • Documentation:

      • Helped to proofread and polish the language of the User Guide and Developer Guide

      • Edited some old diagrams from AddressBook for the purpose of GradTrak (#80)

    • Community:

      • Helped with my teammates' features (checking of prerequisites and graduation requirements) which are closely related to mine (#91, #100, #172)

      • Reported bugs and suggested improvements for other teams in the class (e.g. 1, 2, 3)

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.

Recommend module: rec

Recommends modules that can be read based on the current module plan and course requirements.
Format: rec

  • Modules with unmet prerequisites or those already added (except for failed modules) will not be recommended.

  • Recommended modules are displayed in order of requirement type satisfied: Core, Breadth & Depth, Industry Experience, Faculty, General Education. Modules with the same requirement type satisfied are sorted by level.

If any change is made to the course or module plan, enter rec again to update the recommendation list.

The figure below shows a sample recommendation list for a student studying Computer Science Algorithms with an empty module plan.

recommend
Figure 1. Recommendation list for Computer Science Algorithms

Find module: find

Finds modules in the module plan matching all given module code, semester, grade or finished status.
Format: find [c/MODULE_CODE] [s/SEMESTER] [g/GRADE] [f/IS_FINISHED]

  • Parameters can be in any order and are case-insensitive.

  • Module code can be entered partially, but semester and grade must be in the exact format.

  • For unfinished modules, searching by grade will display those whose grade range covers that grade.

  • Finished status is indicated by y for finished module (i.e. semester read is before current semester) or any other value for unfinished.

Examples:

  • find c/CS
    Lists all modules with "CS" in their codes.

find(c)
Figure 2. Finding modules with "CS"

  • find s/Y1S2
    Lists all modules in Y1S2.

find(s)
Figure 3. Finding modules in Y1S2

  • find g/A f/y
    Lists all finished modules with grade A.

find(g,f)
Figure 4. Finding finished modules with grade A (current semester: Y1S2)

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.

Module recommendation feature

The module recommendation feature displays modules which the student is recommended to read based on the current module plan and specific course requirements. It generates a list of module codes together with their corresponding titles and requirement types satisfied. The entire list is displayed on the Result Panel upon entering the rec command.

Modules which satisfy only Unrestricted Electives are not included to prevent the list from being too long.

Current implementation

Each recommended module is represented by a RecModule which contains a unique ModuleInfo and its corresponding CourseReqType satisfied, as shown in the diagram below.

RecModuleClassDiagram
Figure 5. RecModule class diagram

When ModelManager is initialised, Model#getObservableRecModuleList is called which generates an ObservableList of RecModule , one for each module in the entire ModuleInfoList. This list is wrapped in a FilteredList, which is further wrapped in a SortedList, both stored in ModelManager. At this point, all RecModule in the list contain an empty CourseReqType field.

When the rec command is entered, the sequence of execution is as follows:

  1. Model#updateRecModuleList is called, which creates a RecModulePredicate given the student’s Course and ReadOnlyGradTrak, and a RecModuleComparator.

  2. The RecModulePredicate is applied to the FilteredList of RecModule. In each test:

    1. An EligibleModulePredicate which takes in ReadOnlyGradTrak tests if the ModuleInfo of this RecModule is eligible to be read. If the module is already present in the module plan or does not have its prerequisites satisfied, this RecModule is filtered out.

    2. The ModuleInfoCode (call it codeToTest) of the RecModule is retrieved.
      A nonFailedCodeList of ModuleInfoCode corresponding to non-failed ModuleTaken (already passed or to be read in a future semester) is also retrieved from ReadOnlyGradTrak.

    3. The codeToTest is then passed into Course#getCourseReqTypeOf, which in turn calls CourseRequirement#canFulfill for each CourseRequirement listed in Course. A list of CourseReqType that the codeToTest can satisfy is returned. This courseReqTypeList is sorted by the priority of CourseReqType as defined in the enum class: CORE, BD, IE, FAC, GE.

    4. For each CourseReqType in the courseReqTypeList (highest priority first):

      1. Course#isCodeContributing is called, which takes in the CourseReqType, nonFailedCodeList and codeToTest.

      2. For each CourseRequirement listed in Course corresponding to the given CourseReqType, CourseRequirement#getUnfulfilled is called which takes in the nonFailedCodeList and returns an unfulfilledRegexList of RegExes not satisfied.

      3. If the codeToTest matches any of the RegExes in the unfulfilledRegexList, Course#isCodeContributing returns true and the loop for courseReqTypeList terminates.

    5. The CourseReqType of highest priority satisfied by codeToTest is then set into the RecModule. However, if the codeToTest does not contribute to any of the CourseRequirement listed in Course, this RecModule is filtered out.

  3. The RecModuleComparator is applied to the SortedList of RecModule. It sorts the list in decreasing priority of the CourseReqType satisfied by the RecModule. Those RecModule with equal priority are sorted by module level (the first numerical digit of its ModuleInfoCode), considering that lower level modules are usually read first. In the case of equal priority and module level, lexicographical sorting of its ModuleInfoCode is used.

  4. The SortedList of RecModule is retrieved from ModelManager and displayed to the student in the Result Panel.

If there are changes to ReadOnlyGradTrak (adding, editing or deleting modules) or Course (changing the course of study), the rec command must be run again to reflect the updated recommendation list.

The sequence diagrams summarising the above execution are shown below.

RecCommandSequenceDiagram
Figure 6. RecCommand sequence diagram
RecModulePredicateSequenceDiagram
Figure 7. RecModulePredicate sequence diagram
RecModuleComparatorSequenceDiagram
Figure 8. RecModuleComparator sequence diagram

Design Considerations

Aspect: Sorting of recommendation list

  • Alternative 1 (current choice): Recommendation list is sorted by a fixed order of CourseReqType priority as defined in the enum class

    • Pros: Easy to implement and modify

    • Cons: Student may have his own order of priority that differs from the default one

  • Alternative 2: Recommendation list can be sorted by a custom order defined by the student

    • Pros: Student can sort the list according to his own preferences

    • Cons: Difficult to implement if several parameters for sorting is allowed; input method for the custom order is problematic

Aspect: Format of recommendation

  • Alternative 1 (current choice): Display a list of all eligible modules that contribute to course requirements

    • Pros: Student has a greater freedom of choice

    • Cons: Student may be confused or unable to decide if the list is too long

  • Alternative 2: Display n modules for each semester, where n is decided by the student

    • Pros: Student can plan modules for specific semesters easily and quickly

    • Cons: Algorithm required to plan for all semesters can be complex; student may not prefer the given plan

Possible Improvements

  1. Allow the student to display a module’s information (from displaymod command) using its index in the recommendation list

  2. Allow the student to add a module to the module plan using its index in the recommendation list

  3. Enable recommendation of Unrestricted Electives based on personal interests of the user