Developer Guide

• Acknowledgements
• Setting up, getting started
• Design
  • Architecture
  • UI component
  • Logic component
  • Model component
  • Storage component
  • Common classes
• Implementation
  • Highlight error feature
    • Implementation
    • Design considerations
• Documentation, logging, testing, configuration, dev-ops
• Appendix: Requirements
  • Product scope
  • User stories
  • Use cases
  • Non-Functional Requirements
  • Glossary
• Appendix: Planned Enhancements
• Appendix: Instructions for manual testing
  • Launch and shutdown
  • Adding contacts
  • Deleting contacts
  • Saving data

---

Acknowledgements

• This project is based on the AddressBook-Level3 project created by the SE-EDU initiative.
• Several features was inspired from common programs and/or other CS2103/T teams projects features.

---

Setting up, getting started

Refer to the guide Setting up and getting started.

---

Design

Architecture

The Architecture Diagram given above explains the high-level design of the App.

Given below is a quick overview of main components and how they interact with each other.

Main components of the architecture

Main (consisting of classes Main and MainApp) is in charge of the app launch and shut down.

• At app launch, it initializes the other components in the correct sequence, and connects them up with each other.
• At shut down, it shuts down the other components and invokes cleanup methods where necessary.

The bulk of the app’s work is done by the following 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.

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

How the architecture components interact with each other

The Sequence Diagram below shows how the components interact with each other for the scenario where the user issues the command delete 1.

Each of the four main components (also shown in the diagram above),

• defines its API in an interface with the same name as the Component.
• implements its functionality using a concrete {Component Name}Manager class (which follows the corresponding API interface mentioned in the previous point.

For example, the Logic component defines its API in the Logic.java interface and implements its functionality using the LogicManager.java class which follows the Logic interface. Other components interact with a given component through its interface rather than the concrete class (reason: to prevent outside component’s being coupled to the implementation of a component), as illustrated in the (partial) class diagram below.

The sections below give more details of each component.

UI component

The API of this component is specified in Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel, StatusBarFooter etc. All these, including the MainWindow, inherit from the abstract UiPart class which captures the commonalities between classes that represent parts of the visible GUI.

The UI component uses the JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

• executes user commands using the Logic component.
• listens for changes to Model data so that the UI can be updated with the modified data.
• keeps a reference to the Logic component, because the UI relies on the Logic to execute commands.
• depends on some classes in the Model component, as it displays Person object residing in the Model.

Logic component

API : Logic.java

Here’s a (partial) class diagram of the Logic component:

The sequence diagram below illustrates the interactions within the Logic component, taking execute("delete 1") API call as an example.

How the Logic component works:

1. When Logic is called upon to execute a command, it is passed to an AddressBookParser object which in turn creates a parser that matches the command (e.g., DeleteCommandParser) and uses it to parse the command.
2. This results in a Command object (more precisely, an object of one of its subclasses e.g., DeleteCommand) which is executed by the LogicManager.
3. The command can communicate with the Model when it is executed (e.g. to delete a person).
   Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the Model) to achieve.
4. The result of the command execution is encapsulated as a CommandResult object which is returned back from Logic.

Here are the other classes in Logic (omitted from the class diagram above) that are used for parsing a user command:

How the parsing works:

• When called upon to parse a user command, the AddressBookParser class creates an XYZCommandParser (XYZ is a placeholder for the specific command name e.g., AddCommandParser) which uses the other classes shown above to parse the user command and create a XYZCommand object (e.g., AddCommand) which the AddressBookParser returns back as a Command object.
• All XYZCommandParser classes (e.g., AddCommandParser, DeleteCommandParser, …) inherit from the Parser interface so that they can be treated similarly where possible e.g, during testing.

Model component

API : Model.java

The Model component,

• stores the address book data i.e., all Person objects (which are contained in a UniquePersonList object).
• stores the currently ‘selected’ Person objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiable ObservableList<Person> that can be ‘observed’ e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.
• stores a UserPref object that represents the user’s preferences. This is exposed to the outside as a ReadOnlyUserPref objects.
• does not depend on any of the other three components (as the Model represents data entities of the domain, they should make sense on their own without depending on other components)

Storage component

API : Storage.java

The Storage component,

• can save both address book data and user preference data in JSON format, and read them back into corresponding objects.
• inherits from both AddressBookStorage and UserPrefStorage, which means it can be treated as either one (if only the functionality of only one is needed).
• depends on some classes in the Model component (because the Storage component’s job is to save/retrieve objects that belong to the Model)

Common classes

Classes used by multiple components are in the seedu.address.commons package.

---

Implementation

This section describes some noteworthy details on how certain features are implemented.

Highlight error feature

This feature would automatically highlight (select) the part of the command that contains the error in the command box, so that the user can edit it more quickly.

For example, if the user type edit 1 p/12 c/CS2103T, since the phone number is invalid (but the course code CS2103T is valid), then 12 will be highlighted, which speeds up the process of data entry because the user no longer have to press [←] several times to navigate to 12.

Implementation

First, many functions that originally takes the command string, will now take CommandString, which is a class containing a string.

Compare the old and the new sequence diagram below for the execution of a command. This is the old sequence diagram.

And this is the new sequence diagram.

A class CommandPart is used to maintain a part of a command. For example, if s is a CommandString with value edit 1 p/12 c/CS2103T, then new CommandPart(s).substring(9, 11) returns a CommandPart whose toString() representation is 12, but it also remembers the index into the original CommandString object.

Then, ParseException and CommandExecutionException are two exception classes that implements the CommandException interface. A CommandException has an getErroneousPart() method that returns an Optional<CommandPart>.

When the UI catches a ParseException or CommandExecutionException, it will call getErroneousPart() on the exception object. If the result is not Optional.empty(), it will select the corresponding part in the command box.

Various methods in the parser and the command executor is modified to include the correct command part.

For backwards compatibility, not all CommandException object need to know what part of the command causes the error.

Design considerations

Aspect: How to represent a command string:

• Alternative 1 (current choice): Name the class CommandString.

Aspect: How to represent a part of the command string:

• Alternative 1 (current choice): Name the class CommandPart, and make it specifically only represent a part of a command.
  • Pros: Descriptive class name.
  • Cons: See the pros of alternative 2.
• Alternative 2: Name the class StringPart or equivalent, and make it represent a part of any string.
  • Pros: Later if the need to maintain a substring with reference to the original string shows up in another part of the code, the class can be reused.
  • Cons: See the pros of alternative 1.

Aspect: How to implement common getErroneousPart() method for the exception classes:

• Alternative 1 (current choice): Make an interface CommandException, which exposes getErroneousPart().
  • Pros: Caller can call getErroneousPart() without checking and casting it to CommandExecutionException to ParseException.
  • Cons: Ambiguous semantic. There’s no guarantee a class implementing CommandException also extends Exception.
• Alternative 2: Make an abstract class CommandException, and make both classes inherit from that.
  • Pros: Allows a common implementation for getErroneousPart() without duplicating the code across classes.
  • Pros: Allows code to write catch (CommandException e) instead of catch (ParseException | CommandExecutionException e).
  • Cons: ParseException already inherit from IllegalValueException, and Java does not allow diamond inheritance.
• Alternative 3: Same as alternative 2, but make ParseException no longer inherit from IllegalValueException.
  • Pros: Same as in alternative 2.
  • Cons: Breaks backwards compatibility, because some part of the code may expect catch (IllegalValueException) to also catch a ParseException.

---

Documentation, logging, testing, configuration, dev-ops

• Documentation guide
• Testing guide
• Logging guide
• Configuration guide
• DevOps guide

---

Appendix: Requirements

Product scope

Target user profile:

• has a need to manage a significant number of contacts of NUS students, tutors, and professors
• prefer desktop apps over other types
• can type fast
• prefers typing to mouse interactions
• is reasonably comfortable using CLI apps

Value proposition:

• manage contacts faster than a typical mouse/GUI driven app
• allow NUS students to save and search up contacts of students/tutors/instructors and the courses they are in. (e.g. tutorial/lecture groupings)

User stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Priority	As a …​	I want to …​	So that I can…​
* * *	new user	see usage instructions	refer to instructions when I forget how to use the App
* * *	user	add a new contact
* * *	user	delete a contact	remove entries that I no longer need
* * *	user	edit a contact	change incorrect or new information about a contact
* * *	user	find a contact by name	locate details of contact without having to go through the entire list
* * *	user	find a contact by course code	locate contact from a specific course without having to go through the entire list
*	user	find a contact by tag	find contacts with similar roles quickly
* * *	user	list all contacts	see all contacts at a glance
* *	user	undo the previous command	revert the previous action
* *	user	redo the previous command	redo the previous action
* *	user	tag contacts with custom labels	easily identify their roles in my academic life
* *	user	press [↑] to fill the command-line box with previous commands from command history	edit the last-typed erroneous command quickly
*	user	share a contact with my classmates	collaborate more easily on group assignments
*	user	set reminders to contact instructors before important deadlines	ensure timely communication
*	user	rate and review my interactions with instructors	keep track of my personal experiences and preferences

Use cases

(For all use cases below, the System is the NUSContacts and the Actor is the user, unless specified otherwise)

UC1: Add a contact

MSS

1. User requests to add a contact
2. User provides the contact’s details

3. NUSContacts adds the contact

   Use case ends.

Extensions

• 2a. The contact already exists.

  • 2a1. NUSContacts informs the user of the error.

    Use case ends.

UC2: Delete a contact

MSS

1. User requests to list tutors
2. NUSContacts shows a list of tutors
3. User requests to delete a specific contact in the list

4. NUSContacts deletes the contact

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

• 3a. The given index is invalid.

  • 3a1. NUSContacts shows an error message.

    Use case resumes at step 2.

UC3: Edit a contact

MSS

1. User requests to edit a contact
2. User provides the field to edit and the new value

3. NUSContacts edits the contact

   Use case ends.

Extensions

• 2a. User provides an empty address for a PROFESSOR.

  • 2a1. NUSContacts shows an error message.

    Use case resumes at step 2.

• 2b. User gives a contact without an address the PROFESSOR role.

  • 2b1. NUSContacts shows an error message.

    Use case resumes at step 2.

• 2c. User provides an invalid index such as -1.
  • 2c1. NUSContacts points out where the index is in the command and shows an error message.

  Use case resumes at step 2.

• 2d. User provides a phone number that does not conform to the expected format.
  • 2d1. NUSContacts points out where the phone number is in the command and shows a warning.
  • 2d2. User specify that the warning is to be ignored.

  Use case resumes at step 3.

UC4: Find a contact by name

MSS

1. User requests to find a contact
2. NUSContacts prompts search criterion (name or course code)
3. User provides the search criterion (name)

4. NUSContacts shows the contact(s) that match the criterion

   Use case ends.

Extensions

• 4a. No contact matches the criterion.

  • 4a1. NUSContacts informs the user of the error.

    Use case ends.

UC5: Find a contact by course code

MSS

1. User requests to find a contact
2. NUSContacts prompts search criterion (name or course code)
3. User provides the search criterion (course code)

4. NUSContacts shows the contact(s) that match the criterion

   Use case ends.

Extensions

• 4a. No contact matches the criterion.

  • 4a1. NUSContacts informs the user of the error.

    Use case ends.

UC5: Clear all contacts

MSS

1. User requests to clear all contacts

2. NUSContacts clears all contacts

   Use case ends.

UC6: Clear all contacts

MSS

1. User requests to clear all contacts

2. NUSContacts clears all contacts

   Use case ends.

Extensions

• 2a. The contact already exists.

  • 2a1. NUSContacts informs the user of the error.

    Use case ends.

Non-Functional Requirements

1. Should work on any mainstream OS as long as it has Java 11 or above installed.
2. Should be able to hold up to 1000 contacts without a noticeable sluggishness in performance for typical usage.
3. A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.
4. Error messages displayed to application window should be easily understood by most users.
5. System should respond to user actions within 1 second.
6. For databases with less than 1000 contacts, fetching and saving of contacts to/from it should not exceed 200 milliseconds.
7. System should handle data corruption or loss without crashing the application.
8. System architecture should support future updates and extensions without major restructures.
9. System should support comprehensive testing for all components and features.

Glossary

• Mainstream OS: Windows, Linux, Unix, MacOS
• Private contact detail: A contact detail that is not meant to be shared with others

---

Appendix: Planned Enhancements

Team size: 5

1. Currently, if any component (name, email, etc.) is too long, it will be hidden on the screen. We plan to implement appropriate mechanism to show the full component.
2. Currently, undo only supports undoing one command. We plan to support undoing multiple commands.
3. Currently, using the edit command to edit the tag list will delete all the existing tags and replace it with the new tags. We plan to have ways to edit it incrementally later.
4. Currently, there’s no way to make search more targeted; for example, if there are 3 entries in the address book with name John Doe, Jane Doe and John Smith, then there’s no way to search for specifically John Doe. In the future, we plan to have a way to specify that multiple words must match exactly, and have a priority system where contacts that matches more keywords are shown earlier.
5. Currently, duplicate phone number and email are not detected. We plan to detect them and warn the user of the error.
6. Currently, the result display cannot be resized to view the text in case the text is long. We plan to implement it later.
7. Currently, address is mandatory if the role is Professor, but some profs/lecture track professors might not have offices. We plan to implement a way to allow user have an empty address for Professor by using f/.
8. Currently, f/ bypasses all invalid field value errors, not one of the errors. We plan to implement a way to bypass one by one.

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Launch and shutdown

1. Initial launch

   1. Download the jar file and copy into an empty folder.

   2. Double-click the jar file.
      Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.

2. Saving window preferences

   1. Resize the window to an optimum size. Move the window to a different location. Close the window.

   2. Re-launch the app by double-clicking the jar file.
      Expected: The most recent window size and location is retained.

Adding contacts

1. Adding a contact while all contacts are being shown

   Prerequisites: All existing contacts are to be cleared using clear command. This is to ensure no clashing of contact names while testing.

   1. Test case: add n/Joe Bama e/e0123456@u.nus.edu r/STUDENT c/CS2103T a/In the walls p/91234567
      Expected: New contact with the specified descriptions added to the list and shown in the application.

   2. Test case: add n/Donald Frump e/spammail@gmail.com r/TA c/CS2101
      Expected: Similar to previous, except the “phone” and “address” fields now show (no phone number) and (no address) respectively.

   3. Test case: add n/Hilarious Blipton e/e6969420@u.nus.edu c/DSA1101
      Expected: Contact is not added. Error details shown in the status message.

   4. Test case: add n/Hilarious Blipton e/FAKEEMAIL r/STUDENT c/DSA1101
      Expected: Similar to previous.

   5. Test case: add n/Joe Bama e/e0123456@u.nus.edu r/STUDENT c/CS2103T a/In the walls p/91234567
      Expected: Similar to previous. (This test must be done after the first test case)

   6. Test case: add n/Hilarious Blipton n/Not Elden Clinton e/e6969420@u.nus.edu r/STUDENT c/DSA1101
      Expected: Similar to previous.

   7. Other incorrect add commands to try: add, adding ..., ....
      Expected: Similar to previous.

Deleting contacts

1. Deleting a contact while all contacts are being shown

   Prerequisites: List all contacts using the list command. Multiple contacts already in the list.

   1. Test case: delete 1
      Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated.

   2. Test case: delete 0
      Expected: No contact is deleted. Error details shown in the status message. Status bar remains the same.

   3. Other incorrect delete commands to try: delete, delete x, ... (where x is larger than the current list size).
      Expected: Similar to previous.

2. Deleting multiple contacts while all contacts are being shown

   Prerequisites: List all contacts using the list command. Multiple contacts already in the list.

   1. Test case: delete 1 2
      Expected: No contact is deleted. Error details shown in the status message. Status bar remains the same.

   2. Test case: delete 1, 2
      Expected: First 2 contacts are deleted from the list. Details of the deleted contacts shown in the status message. Timestamp in the status bar is updated.

   3. Other incorrect delete commands to try: delete 1, 0, delete 1, 3, x, ... (where x is larger than the current list size)
      Expected: Similar to the first test case.

Saving data

1. Dealing with missing/corrupted data files

   1. Close the application, and delete the data file (if it exists).

   2. Re-launch the application.
      Expected: The data file is re-created and populated with sample data.

   3. Close the application, and modify the data to be invalid.

   4. Re-launch the application.
      Expected: The program reports the data file is corrupted, and start with an empty address list.

   5. Add some entry into the address book.
      Expected: The new data is saved into the save file.