PROJECT: ClassRepo

Introduction

The purpose of this portfolio is to document the specific contributions I have made to this project. The project was carried out over the course of one semester in the National University of Singapore(NUS), under the module CS2113T, which aims to teach Software Engineering principles and Object-Oriented Programming. ClassRepo was done by a team of 5 including myself.

Project Overview

ClassRepo is a desktop address book application written in Java that targets secondary schools for usage by their students, tutors and admins. It serves to integrate all the functionalities that the user would need in their seconday school lives and/or school operations. The user interacts with it using a CLI, and it has a very basic GUI. It is an enhanced version of the AddressBook Level-3 application by the sed-edu team.

Role

I served as the project’s bug tester, to ensure that each feature added will be as bug-free as possible. I also became a point of contact should any of my group’s members require technical help in developing their respective features and participated in group discussions.

Summary of contributions

  • Code contributed: here

  • Main feature implemented: added the Exams feature

    • What it does: allows staff to create and manage exams held in the school, as well as registering students for them.

    • Justification: This feature improves the product significantly because exams would be present in every school and it would be valuable for the school tutors and admins to manage them in a single application. Students would be able to benefit as they can check their exam schedules without the need to ask others or record them separately.

    • Highlights: This enhancement affects existing commands, data structures and commands to be added in future. It required an in-depth analysis of design alternatives. The implementation too was challenging as it required changes to existing commands and data structures. This is because a single exam object is closely related to the whole AddressBook. Hence, there are checks to ensure that the exams are always synchronised in both storage files.

    • Credits: Victor Hernandez for the base valid date checker method.

  • Other contributions:

    • Contributions to project management:

      • Helped to manage issues posted in GitHub

    • Enhancements to existing features:

      • Split test code to different folders for better organisation: #205

    • Contributions to project documentation:

      • Helped to port over and adapted AddressBook - Level 4 documents to ensure working links for website: #156, #206

      • Standardised format for documentation: #184

      • Helped to update the AboutUs page: #185

    • Evidence of helping others:

      • PRs reviewed (with non-trivial review comments): #68

      • Helped to write tests for others and increase coverage: #284

      • Manually tested all features in my team’s application and reported any issues: #161, #173, #246, #269

      • Manually tested other teams' applications and reported any issues: #192, #197, #203, #211

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.

Exam Commands

Below are the commands that deals with exam data:

Adding an exam : addexam 16

Adds an exam to the exam book, with the number of takers initialised as 0.
Format: addexam [p]e/EXAM_NAME s/SUBJECT_NAME d/EXAM_DATE st/EXAM_START_TIME et/EXAM_END_TIME dt/EXAM_DETAILS

Words in UPPER_CASE are the parameters, items in SQUARE_BRACKETS are optional. Order of parameters is fixed.
Put a p before the exam name prefix to mark the exam as private.

Example(s):

  • addexam e/Math 2018 Finals s/Mathematics d/01-12-2018 st/09:00 et/12:00 dt/At MPSH

  • addexam pe/2017 English Finals Paper 2 s/English d/01-12-2017 st/08:00 et/10:00 dt/No Pencils Allowed

Listing all exams : listexams 16

Shows a list of all exams in the exam book.
Format: listexams

Deleting an exam : deleteexam 16

Deletes the specified exam from the exam book. Irreversible. Persons registered for the corresponding exam will have the exam deleted as well.
Format: deleteexam INDEX

Deletes the exam at the specified INDEX. The index refers to the index number shown in the most recent exams listing.

Example(s):

  • listexams
    deleteexam 2
    Deletes the 2nd exam in the exam book.

Editing an exam : editexam 16

Edits the specified exam from the exam book. Persons registered for the corresponding exam will have the exam details updated as well.
Format: editexam INDEX [p/PRIVATE_STATUS] [e/EXAM_NAME] [s/SUBJECT_NAME] [d/EXAM_DATE] [st/EXAM_START_TIME] [et/EXAM_END_TIME] [dt/EXAM_DETAILS]

Edits the exam at the specified INDEX. The index refers to the index number shown in the most recent exams listing. Words in UPPER_CASE are the parameters, items in SQUARE_BRACKETS are optional. Order of parameters is fixed. At least 1 item in SQUARE_BRACKETS must be present.

PRIVATE_STATUS is denoted by y for private and n for non-private.

Example(s):

  • listexams
    editexam 2 p/y e/English 2018 Finals dt/In MPSH

  • listexams
    editexam 1 dt/Cancelled

Registering for an exam : regexam 16

Registers a specified person for a specified exam.
Format: regexam PERSON_INDEX EXAM_INDEX

Registers the person at the specified PERSON_INDEX for the exam at the specified EXAM_INDEX. The PERSON_INDEX refers to the index number shown in the most recent persons listing. The EXAM_INDEX refers to the index number shown in the most recent exams listing.

Changes to an exam in the exam book will change the corresponding exam for all persons registered under it, be it an 'edit' or a 'delete'. Exams registered for a person will not be shown in the list command and only viewable under the viewall, viewself and viewexams command.

Example(s):

  • listexams
    list
    regexam 2 2
    Registers the 2nd person in the address book for the 2nd exam in the exam book.

Deregistering for an exam : deregexam 16

Deregister a specified person for a specified exam.
Format: deregexam PERSON_INDEX EXAM_INDEX

Deregisters the person at the specified PERSON_INDEX for the exam at the specified EXAM_INDEX. The PERSON_INDEX refers to the index number shown in the most recent persons listing. The EXAM_INDEX refers to the index number shown in the most recent exams listing.

Example(s):

  • listexams
    list
    deregexam 2 2
    Deregisters the 2nd person in the address book for the 2nd exam in the exam book.

Viewing exams : viewexams 16

View the exams for a specified person in the address book.
Format: viewexams INDEX

Views the exams of the person at the specified INDEX. The index refers to the index number shown in the most recent persons listing.

This command will work for all INDEX only when the user is of Tutor and Admin privileges.
If the user has no privileges, the user must be logged into an account and can execute the command to view only his own non-private exams.

Example(s):

  • login user pw
    list
    viewexams 1
    Views the non-private exams of the 1st person in the address book, if the logged-account belongs to him/her.

  • login admin admin
    list
    viewexams 1
    Views the exams of the 1st person in the address book, if the logged-account belongs to a tutor/admin.

Clearing all entries : clearexams 16

Clears all entries from the exam book. All exams will be cleared in the address book as well.
Format: clearexams

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.

Exams Feature

Exam
Figure 1. Class Diagram of the Exam feature

Current Implementation

There is a master ExamBook which contains all the exams. There are several features the ExamBook offers. The main features are:

  1. Adding a new exam

  2. Deleting an exam

  3. Editing an exam

  4. Registering a person for an exam

  5. Deregistering a person for an exam

Changes to the master ExamBook will affect the corresponding exams in the AddressBook. This is done through iterating through the AddressBook to update the change. Changes in the AddressBook will also affect the exams the persons registered for in the ExamBook and hence, for other persons in the AddressBook. This is also done through iterating.

An Example of how feature 5 - Registering a person for an exam works:

  1. First, the specific exam and person will be identified from the most recent exams and persons listing respectively.

  2. The specific exam and person is then extracted out of the ExamBook and AddressBook respectively.

  3. A check is performed to ensure the specific person is not already registered for the exam.

  4. A new exam is created to keep a copy of the original exam.

  5. The exam has its number of exam takers increased by 1.

  6. The exam is added to the specific person.

  7. For the AddressBook, any copies of the original exam are removed and replaced with the new exam.

This is demonstrated by the following sequence diagram:

RegisterExam Sequence Diagram
Figure 2. Sequence Diagram of registering a person for an exam with no errors occurring

Design Considerations

Aspect: How the exam data are being synchronised between the AddressBook and ExamBook

  • Alternative 1 (current choice): Each time there is a change in the field of an Exam, there has to be iteration through the whole AddressBook or ExamBook to update them.

    • Pros: Less space is needed.

    • Cons: This can waste some time if no changes need to be made for example.

  • Alternative 2: Store the persons registered for an exam for each exam.

    • Pros: This makes it faster to update any changes in both AddressBook and ExamBook if needed.

    • Cons: More data is duplicated and stored in both AddressBook and ExamBook.

Aspect: How the exam data are being updated

  • Alternative 1 (current choice): Each time there is a change in a field of an Exam, a new Exam is created with the new details and added into the ExamBook and the old Exam is deleted from the ExamBook.

    • Pros: To enable good synchronisation between the AddressBook and ExamBook as the old hash key is removed and a new hash key is added.

    • Cons: Temporary increase in space for the object created during the method.

  • Alternative 2: Edit the original exam directly.

    • Pros: Easy access to set values.

    • Cons: To check if an exam exists for a person, there needs to be iteration and checks using the equals() method due to different hashing, increasing time.

Aspect: Exam equality

  • Alternative 1 (current choice): The current equals() method does not check for full equality.

    • Pros: This is used when there is not a need to check for full equality, such as when adding a new exam to the ExamBook.

    • Cons: Another method is needed to check for full equality.

  • Alternative 2: Have the current equals() method check for full equality, with no extra methods.

    • Pros: Fewer methods and easier to understand implementation.

    • Cons: Duplicate exams can be added, especially after modification of an exam in the ExamBook.

Aspect: Data structure to support the exam commands

  • Alternative 1 (current choice): Exams are stored in a set under each Person object in the AddressBook but stored as a list in the ExamBook.

    • Pros: In the Exambook, it is required to access an exam through an index to delete and edit, hence list is better. In the AddressBook, exams are only to be used for viewing and accessed to check for the value. It takes O(1) time to check for existence and remove and add.

    • Cons: Exams stored under each Person in the AddressBook cannot be sorted.

  • Alternative 2: Exams are stored as a list in both ExamBook and AddressBook.

    • Pros: Exams stored under each Person in the AddressBook can be sorted.

    • Cons: It takes O(n) time (longer time) to check if a Person has a same Exam with the Exam to be updated.

Aspect: Storage of ExamBook

  • Alternative 1 (current choice): Exams are stored in a separate txt file from AddressBook

    • Pros: This allows for clarity and easy access to find and see exams in raw XML format.

    • Cons: Extra storage file and hence methods and file paths are needed, this may be confusing and cause much repetition of code.

  • Alternative 2: Exams are stored in the same data file as AddressBook.

    • Pros: Only 1 storage file is needed. Less repetition and variables are needed.

    • Cons: Might be harder for the user to see exams in raw XML format as everything is stored together.