Tian Xueyan - Project Portfolio

Overview

TheTracker is a desktop address book application that helps NUS students to monitor contacts, modules and events.

Summary of contributions

Major enhancement: extended AddCommand to AddPersonCommand, AddModuleCommand, AddOccasionCommand
- What it does: allows the user to adds Person, Module, and Occasion to their own TheTracker. Any Persons, Modules and Occasions added by users in the command line will show in separate windows. It also allows users to input only one compulsory attribute to add one Person, Module or Occasion.
- Justification: These features are the basics of the product such that a user can track his or her contacts, modules and occasions happening in the school. It is more convenient for the users to input any number of optional attributes when they are adding the Person, Module and Occasion, and to update these optional attributes at any time they feel needed, rather than requiring the users to input all the attributes at the first place.
Minor enhancement: extended FindCommand to FindPersonCommand, FindModuleCommand, FindOccasionCommand
- What it does: allows the user to finds Person by name, phone, or email, address, modules they are taking, and occasions they are involved in; similarly, it allows finding Modules and Occasions by respective attributes.
- Justification: These features largely improve the convenience for finding a specific Person, Module or Occasion. For instance, a Person now can be found by his or her name, phone, email, address, module code of the module he is taking, and occasion name of the occasion he is involved in. Multiple steps of findperson command can be used to find a person by more than one kind of conditions.
Minor enhancement: built tests for Occasion related classes, and unit and system tests for the above-mentioned commands.
Code contributed: [Code]
Other contributions: wrote skeleton for Occasion related UI.
- Project management:
  - Set milestones for v1.2 - v1.4 on GitHub
  - Opened issues for v1.2 - v1.4 on GitHub
- Enhancements to existing features:
  - Updated Add and Find related Commands (Pull requests #94, #111)
  - Wrote additional tests for existing features to increase coverage(Pull requests #98, #115)
- Documentation:
  - Did cosmetic tweaks to existing contents of the User Guide: #202
- Community:
  - PRs reviewed (with non-trivial review comments): #108, #121,
  - Some parts of the history feature I added was adopted by several other class mates (125)

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.

Adding an entry: `add` + `person`

A person, module or an occasion can have any number of tags (including 0) and in no particular order.

Adding a person: `addperson`

A command to allow user to add a person to TheTracker.

Format:
addperson n/NAME [p/PHONE_NUMBER] [e/EMAIL_ADDRESS] [a/HOME_ADDRESS] [t/TAG]…

Example:
addperson n/John Doe
addperson n/John Doe p/98765432 e/johnd@example.com a/311, Clementi Ave 2, #02-25 t/friends t/owesMoney

Notice

Persons with the same Name and either one or both of Phone and Email are considered to be the same person.
Name must be specified to create a person contact.
If not enetered, Phone number, Email Address, Home Address and tags are empty.

Adding a module: `addmodule`

A command to allow user to add a module to TheTracker.

Format:
addmodule mc/MODULE_CODE [mt/MODULE_TITLE] [ay/ACADEMIC_YEAR] [sem/SEMESTER] [t/TAG]…

Example:
addmodule mc/CS2103
addmodule mc/CS2103 mt/SOFTWARE ENGINEERING ay/1718 sem/1 t/gg

Notice

Module with the same Module Code, Academic Year and Semester are considered to be the same module.
Module Code must be specified to create a module.
If not entered, Academic Year, Module Title, Semester and Tags are empty.
Semester number 3 and 4 are used to refer to special terms at NUS.

Adding an occasion: `addoccasion`

A command to allow user to add an occasion to TheTracker.

Format:
addoccasion on/OCCASION_NAME [od/OCCASION_DATE] [loc/LOCATION] [t/TAG]…

Example:
addoccasion on/discussion
addoccasion on/discussion od/2018-01-01 loc/SoC t/project t/gg

Notice

Occasion with the same Occasion Name and Occasion Date are considered to be the same occasion.
Occasion Name must be specified to create an occasion. The length of Occasion Name should be between 3 - 30.
If not entered, Occasion Date, Occasion Location and Tags are empty.

Locating entries: `find` + `person`

Finding a person: `findperson`

A command to allow the user to find a person in TheTracker.

Format:
findperson n/NAME, findperson p/PHONE_NUMBER, findperson e/EMAIL_ADDRESS, findperson a/ADDRESS, findperson mc/cs2103

Example:

findperson n/John Doe
findperson p/98765432
findperson e/johnd@example.com
findperson a/Clementi

Finding a module: `findmodule`

A command to allow the user to find a module in TheTracker.

Format:
findmodule mc/MODULE_CODE, findmodule mt/MODULE_TITLE, findmodule ay/ACADEMIC_YEAR, findmodule sem/SEMESTER

Example:

findmodule mc/CS2103, findmodule mt/SOFTWARE, findmodule ay/AY1718, findmodule sem/1

Finding an occasion: `findoccasion`

A command to allow the user to find an occasion in TheTracker.

Format:
findoccasion on/OCCASION_NAME, findoccasion od/OCCASION_DATE, findoccasion loc/LOCATION

Example:

findoccasion on/discussion, findoccasion od/2018-01-01, findoccasion loc/SoC

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.

Add Person/Module/Occasion Feature

The add feature is currently implemented the same way to add persons, modules and occasions. There are thus three similar commands which are related to this add command: addperson, addmodule, addoccasion.

The add command adds the entity (person, module, occasion) with the attributes / fields provided by the user.

Current Implementation

As the addperson, addmodule, addoccasion commands' logic are similar to one another, the addperson command will be taken as the sole example in this document.

AddPersonCommand extends the Command class and uses inheritance to facilitate implementation. Its mechanism is facilitated by VersionAddressBook. In addition, it implements the following operations: * VersionedAddressBook#addPerson(Person): Update the targetedPerson with edited fields * VersionedAddressBook#commit(): Saves the current book state in the command history

Provided below is a usage scenario instance. It illustrates how the add mechanism behaves at each step.

Step 1: The user launches TheTracker for the first time. The VersionedAddressBook will be initialised with the initial address book state, which the currentStatePointer is currently pointing to.

Step 2: The user executes addperson n/David… command to add a person named David in his TheTracker. The addperson string input in the command line is passed into the AddressBookParser object, which parses the input and creates an AddPersonCommandParser to help it further parse the argument. This AddPersonCommandParser creates a Person with the Compulsory attribute Name, and optional fields Phone, Email, Address and Tag as provided by the user and passes this person to be added to a new AddPersonCommand. The addPersonCommand calls Model#addPerson(), thus adding the new Person into the versionedAddressBook. The addperson command then calls Model#commitAddressBook(), causing the modified state of TheTracker after the addperson n/ David… command executes to be saved in the addressBookStateList.

The following sequence diagram shows how the addperson operation works: addperson n/David

addmodule and addoccasion works in a similar way as addperson

Design Considerations

Aspect: How addperson/addmodule/addoccasion executes

Alternative 1 (Current Implementation): AddPersonCommand, AddModuleCommand and AddOccasionCommand require users to input only one compulsory attribute, and may also add any number of optional attributes.
- E.g. addperson n/David, addmodule mc/CS2103, addoccasion on/project meeting are the easiest way to add a person, module and occasion
- Pros: This is more user friendly, such that users can add a contact even they only know the name of the contact. And, they can input details of that contact if needed.
- Cons: This may be hard for the storage of TheTracker, and needs to work compatibly with other features.
Alternative 2: AddPersonCommand, AddModuleCommand and AddOccasionCommand require users to input all pre-defined attributes.
- Pros: Easy to implement.
- Cons: Less flexible, such that users cannot add in a contact with some details they do not know.

Find Person/Module/Occasion Feature

The find feature currently is implemented the same way to find persons, modules, and occasions. There are thus three similar commands which are related to this find command: findperson, findmodule, and findoccasion.

The find command family finds the entity (person, module, occasion), based on their attributes / fields.

The figure below shows how the find command is processed through the logic of TheTracker:

Current Implementation

As the findperson, findmodule, and findoccasion commands' logic are similar to one another, the findperson command will be taken as the sole example in this document. The findperson string input in the command line is passed into the AddressBookParser object, which parses the input and creates a FindPersonCommandParser to help it further parse the argument and create a FindPersonCommand. This FindPersonCommand filters the entire person list based on the keyword in the specific field stipulated and updates the Address Book Model to create an Observable List of persons based on the filter specified.

Design Considerations

Aspect: How find executes

Alternative 1 (current choice): Match full keyword.
- E.g. If there is a person named "Alex", only the command findperson n/alex will find the person. findperson n/ale will not find the person.
- Pros: Very target and precise finding of person.
- Cons: Cannot find parts of the person’s attributes especially if user cannot remember full attribute name, title, etc.
Alternative 2: Match keyword to part of the attribute.
- E.g. If there is a person named "Alex", the commands findperson n/e, findperson n/ex, findperson n/le, findperson n/alex will find the person.
- Pros: Can find multiple entries of persons with keyword in name.
- Cons: May not limit the search of persons, hard to pinpoint exact person. Class Diagram for Module:

Class Diagram for Occasion: