PROJECT: RecruitBook


Overview

This Project Portfolio documents my role and contributions to this project.

RecruitBook is a project created for my core module [CS2113T Software Engineering] in my second year in National University of Singapore(NUS). My team consists of 5 members, with a mixture of undergraduates majoring in Computer Engineering and undergraduates majoring in Information Security. The project requirement was to morph an AddressBook application into something that responds to social needs and offers sustainable solutions.

My role in this project is a developer and my responsibilities are ensuring code quality and updating documentation. I believe that documentation is as important as coding, because chunks of code do not make sense without proper explanation and justification. It is essential in a group project to update our teammates with the changes, to keep everyone on the same page.

RecruitBook is an offline desktop application that allows you to manage candidates and job offers throughout the process of recruiting. The user interacts with it using a CLI, and it has a GUI created with JavaFX. It is written in Java, and has about 10 kLoC.

Summary of contributions

  • Major enhancement: added a Shortlist feature

    • What it does: It allows the user to shortlist a candidate for a selected job offer of a selected company.

    • Justification: This feature improves the product significantly as a user can link up the potential candidates to suitable job offers.

    • Highlights: This enhancement required an in-depth analysis of design alternatives as to how the shortlisted candidates are stored and displayed.

  • Major enhancement: redesigned the User Interface(UI) to suit RecruitBook

    • What it does: It allows the user to switch view between Candidate Book and Company Book, as well as interact with the items displayed on the screen.

    • Justification: This feature is essential in the product as it manages the data of both candidates and companies. In order to benefit the user, the app should organise the way data is displayed to the user.

  • Minor enhancement:

    • StatusFooterBar at the bottom of the application keeps track of the total number of candidates and companies, as well as their last updated time and locations of the files saved.

    • Credits: StatusFooterBar

  • Code contributed: Under the username of leerachel.

  • Other contributions:

    • Project management:

      • Managed releases v1.1 - v1.4 (4 releases) on GitHub

    • Documentation:

      • Did cosmetic tweaks to existing contents of the User Guide and reorganised Developer Guide: here

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. I have written for switch, select, shortlist, deleteShortlist, list, but will only include shortlist here due to page limit.

Shortlisting candidates for a job offer : shortlist

Shortlisting process is a 5-stage process. To exit from this process, enter cancel command as explained in [Exits from any intermediate command: cancel]. You cannot shortlist a blacklisted candidate or the same candidate who is already shortlisted for the same job offer.

Format: shortlist

  1. Initialization

    1. Type shortlist and press Enter to initialize the shortlist process.

  2. Choose the company

    1. Type selectC <INDEX> and press Enter to select the company.

      You can use sortC, findC or filterC command to easily locate the company before selecting it.
  3. Choose the job offer

    1. Type selectj <INDEX> and press Enter to select the job offer.

      You can use sortj command to easily locate the job offer before selecting it.
  4. Choose the candidate

    1. Type selectc <INDEX> and press Enter to select the candidate to shortlist.

      You can use sortc, findc or filterc command to easily locate the candidate before selecting.
  5. Confirm the details

    1. Type confirm and press Enter to confirm.

Index must be an index number shown in the displayed list.

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. I have also edited the other parts to make sure they are coherent.

Switch Book Feature

Current Implementation

The switching mechanism is facilitated by MainWindow, with the latter’s switchToCandidateBook and switchToCompanyBook methods.

It extends Command with EventsCenter, where it uses EventsCenter to post a new SwitchBookRequestEvent so that MainWindow will handle the event with its handleSwitchBookEvent method.

MainWindow knows an event is posted because it is subscribed to the event bus com.google.common.eventbus.Subscribe. It will handle any event that matches the parameter of the handling methods in MainWindow class. For example, SwitchBookRequestEvent will match with the handleSwitchBookEvent(SwitchBookRequestEvent event) as the parameter matches.

As mentioned above, inside MainWindow, there are 5 placeholders and the panelViewPlaceholder can hold either CandidateDetailsPanel, CompanyJobDetailsPanel or ShortlistPanel.

The methods switchToCandidateBook and switchToCompanyBook work by placing the desired panel in panelViewPlaceholder, to be shown on the MainWindow.

Given below is an example usage scenario for switching from Candidate Book to Company Book and how the switching mechanism behaves at each step.

  1. User launches the application. MainWindow initialises the panelViewPlaceholder with CandidateDetailsPanel.

    This means the default view of RecruitBook is the Candidate Book.
  2. User executes switch command, which posts a SwitchBookRequestEvent.

  3. MainWindow handles the posted SwitchBookRequestEvent with its method handleSwitchBookEvent.

  4. Inside this method, it checks which book is currently displayed by calling the method getDisplayedBook.

  5. getDisplayedBook returns candidateBook as a string.

  6. Using a switch statement, case candidateBook will execute and call for switchToCompanyBook method.

  7. switchToCompanyBook method places the CompanyJobDetailsPanel into panelViewPlaceholder to switch the view

    In order to add a panel into panelViewPlaceholder, the existing panel needs to be removed so that there will not be duplicated panels inside panelViewPlaceholder. There will be a compilation error if there are duplicated panels.

Design Considerations

Aspect: How switch feature executes
  • Alternative 1 (current choice): Use EventsCenter to post events and MainWindow to handle these events.

    • Pros: Easy to implement. Neat and clean code with less coupling. MainWindow has private methods and variables to prevent unauthorised access for better integrity purposes.

    • Cons: -

  • Alternative 2: Allow all methods in MainWindow to be static and public.

    • Pros: Other classes can have easy access to the switching methods and their variables.

    • Cons: May face integrity issues due to public access of MainWindow. Increases unnecessary coupling.

Aspect: Data structure to support the switch feature
  • Alternative 1 (current choice): The only variable that MainWindow has to keep track of is currentBook.

    • Pros: Easy to keep track as currentBook is set to candidateBook or companyBook accordingly.

    • Cons: currentBook is a string variable. Misspelling of candidateBook or companyBook in code may result in a bug.

  • Alternative 2: Store currentBook as boolean isCandidateBook, with the boolean returning true if the current book is Candidate Book, and returning false if the current book is Company Book.

    • Pros: Eliminates the possibility of misspelling the books.

    • Cons: Can be confusing for multiple contributors. There is also an assumption that there are only 2 distinct cases of the view of panelViewPlaceholder, which is not the case as we introduced another view ShortlistPanel.

Shortlist Feature

Current Implementation

Shortlisting a Candidate

The shortlist mechanism is facilitated by selectc, selectC and selectj command. The parsing of these commands is facilitated by ShortlistParser.

It extends CompanyBook with a list of shortlisted candidate(s) for each job offer, stored internally as a Unique Candidate List called candidateList. The reason for storing as a unique list is to prevent duplicated candidates from being added into the same candidateList. It also uses EventsCenter to post a new ChangeLogicStateEvent so that LogicManager will handle the event with its handleChangeLogicStateEvent method.

It is a 5-stage process supported by LogicManager by keeping track of the LogicState.

  1. primary

  2. SelectCompanyForShortlist

  3. SelectJobForShortlist

  4. SelectCandidate

  5. ShortlistCandidate

Given below is an example usage scenario and how the shortlist mechanism behaves at each step.

x refers to the index from user input.
  1. User launches the application. RecruitBook sets up the Candidate Book and Company Book respectively.

    Assume that there are candidates and companies present in the data of RecruitBook, but no job offer.
  2. User adds a new job offer Cashier under the existing company KFC.

    Since RecruitBook opens up Candidate Book by default, adding a job offer will automatically switch the view to Company Book.
  3. RecruitBook creates a new object Cashier with JobOffer class. Hence, Cashier has candidateList as one of its attributes.

    candidateList is empty upon creation of the Cashier object.
  4. User executes shortlist command. The view changes from Company Book to ShortlistPanel. ShortlistPanel lists out all the candidates, companies and job offers.

  5. RecruitBook enters Stage 2 of the shortlisting process to shortlist a candidate for a job offer. This is implemented by LogicManager where setLogicState is called in each stage to connect one after another. User will need to execute cancel command to exit from the shortlist process. The 5-stage process is described in order below.

    1. shortlist → User initializes the shortlisting process.

    2. selectC x → User selects the company of the job offer.

      sortC, findC and filterC commands can be used to easily locate the company before selecting it.
    3. selectj x → User selects the job offer.

      sortj command can be used to easily locate the job offer before selecting it.
    4. selectc x → User selects the candidate to shortlist.

      sortc, findc and filterc commands can be used to easily locate the candidate before selecting.
    5. confirm → User confirms the above inputs.

  6. RecruitBook proceeds to add shortlisted candidate through Model. ModelManager connects the candidateList of the job offer in JobOffer class to Model, which then connects to Command.

  7. Model.shortlistCandidateToJobOffer() method adds the shortlisted candidate into the candidateList.

  8. candidateList is linked to the job offer.

    You can access this list by calling selectedJob.getUniqueCandidateList().
  9. model.commitRecruitBook() is then called to indicate that Company Book has been changed.

  10. RecruitBook exits the shortlisting process and returns your view to your last viewed book.

The following sequence diagram shows how the shortlist operation works:

shortlistSequenceDiagram

The following activity diagram summarizes what happens when a user executes shortlist command:

shortlistActivityDiagram
Deleting a Shortlisted Candidate

Deletion of a shortlisted candidate uses similar implementation as Shortlisting a Candidate.

The shortlist mechanism is facilitated by selectC and selectj command. The parsing of these commands is facilitated by ShortlistParser.

It deletes a shortlisted candidate from the candidateList through Model.

Deleting a shortlisted candidate does not delete the candidate from Candidate Book. It simply removes the candidate from the list of shortlisted candidates for that particular job offer.

It also uses EventsCenter to post a new ChangeLogicStateEvent so that LogicManager will handle the event with its handleChangeLogicStateEvent method.

It is a 4-stage process supported by LogicManager by keeping track of the LogicState.

  1. primary

  2. SelectCompanyForShortlistDelete

  3. SelectJobForShortlistDelete

  4. DeleteShortlistedCandidate

Given below is an example usage scenario and how the delete mechanism behaves at each step.

x refers to the index from user input.
  1. User launches the application. RecruitBook sets up the Candidate Book and Company Book respectively.

    Assume that there is at least one shortlisted candidate for the job offer selected by user.
  2. User executes deleteShortlist command.

    Since RecruitBook opens up Candidate Book by default, entering the delete process for shortlisted candidates will automatically switch the view to Company Book.
  3. RecruitBook enters Stage 2 of the deleting process. This is implemented by LogicManager where setLogicState is called in each stage to connect one after another. User will need to execute cancel command to exit from the shortlist process. The 4-stage process is described in order below.

    1. deleteShortlist → User initializes the deleting process.

    2. selectC x → User selects the company of the job offer.

      sortC, findC and filterC commands can be used to easily locate the company before selecting it.
    3. selectj x → User selects the job offer.

      sortj command can be used to easily locate the job offer before selecting it.
    4. delete x → User selects the candidate to delete.

  4. RecruitBook proceeds to delete the shortlisted candidate through Model. ModelManager connects the candidateList of the job offer in JobOffer class to Model, which then connects to Command.

  5. Model.deleteShortlistedCandidateFromJobOffer() method deletes the shortlisted candidate from the candidateList.

    This command checks if the selected candidate exists inside candidateList by evaluating a boolean statement selectedJob.getUniqueCandidateList().contains(selectedCandidate). If the candidate does not exists inside the list, this command returns a message to be displayed to inform the user.
  6. model.commitRecruitBook() is then called to indicate that Company Book has been changed.

  7. RecruitBook exits the deleting process.

The following activity diagram summarizes what happens when a user executes deleteShortlist command:

deleteShortlistActivityDiagram

Design Considerations

Aspect: How shortlist feature executes
  • Alternative 1 (current choice): Use existing selectc, selectC and selectj commands.

    • Pros: Easy to implement.

    • Cons: May have performance issues in terms of memory usage.

  • Alternative 2: Shortlist command executes the 5-stage process by itself.

    • Pros: Does not need to rely on LogicManager to facilitate the process.

    • Cons: We must implement 3 fields for user input shortlist Candidate/[input] Company/[input] Job/[input] and store separately from the Candidate Book and Company Book. Furthermore, we have to filter by job offer and store the data into an observable list on the UI when the user wants to view the shortlisted candidates for a certain job offer.

Aspect: Data structure to support the shortlist feature
  • Alternative 1 (current choice): Use a list to store the shortlisted candidates and attach this list to the respective job offer.

    • Pros: Easy for new Computer Science student undergraduates to understand, who are likely to be the new incoming developers of our project.

    • Cons: Increases coupling between JobOffer and ShortlistCandidateCommand.

  • Alternative 2: Use a HashMap to store the shortlisted candidates as the key and the respective job offers as the value.

    • Pros: We do not need to set shortlistedCandidateList as an attribute in each the JobOffer object. This would use less memory as it only takes a HashMap to store all the shortlisted candidates along with the job offers. Furthermore, this reduces coupling between JobOffer and ShortlistCandidateCommand.

    • Cons: HashMap only allows unique keys. In other words, HashMap does not allow duplicates of candidates to be stored. However, in RecruitBook, user should be able to shortlist a candidate for multiple job offers. Hence, we need to further implement a list of job offers to be stored as the value for each candidate so as to store multiple job offers under the same candidate key.