Intelli - Developer Guide

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

After forking the repo, links in the documentation will still point to the se-edu/addressbook-level4 repo. If you plan to develop this as a separate product (i.e. instead of contributing to the se-edu/addressbook-level4) , you should replace the URL in the variable repoURL in DeveloperGuide.adoc and UserGuide.adoc with the URL of your fork.

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

When you are ready to start coding,

Aspect: Type of command implemented
Alternative 1 (current choice): Command
Pros: Simple to implement; undo / redo mechanism does not need to know how to interact with Storage to undo a backup.
Cons: Accidental backups may be invoked, potentially overwriting an existing backup.
Alternative 2: UndoableCommand
Pros: Possible to undo a backup; prevents accidental overwrites of an existing backup.
Cons: The undo / redo mechanism needs to be extended to be able to redo / undo backups, increasing interaction with the Storage component.

Aspect: Location of backup file
Alternative 1 (current choice): data/intelli.xml.bak
Pros: Easy to locate for the user; file is always in a predictable location.
Cons: Accidental backups may be invoked, potentially overwriting an existing backup in the same location.
Alternative 2: Add a timestamp to the backup filename
Pros: Will not overwrite existing backups, can serve as rudimentary version control mechanism.
Cons: User may not be aware of how many backups they have created; might cause a lot of backups to exist, creating confusion.

Aspect: Interaction between Command and StorageManager
Alternative 1 (current choice): Extend setData() to also recieve the Storage component
Pros: In line with existing architecture, does not introduce global state.
Cons: All invocations of setData() have to be changed; but only one command uses StorageManager, creating unnessasary busywork.
Alternative 2: Make StorageManager a Singleton
Pros: Does not affect existing commands; easy for BackupCommand to access.
Cons: Changes architecture of app, introduces more global state.

Aspect: Implementation for addRelationship command
Alternative 1 (current choice): The command is implemented by adding one additional attribute UniqueRelationshipList to each person.
Pros: Implementation is easier as it follows the same logic as having the UniqueTagList.
Cons: All the relationships in the address book are not organized into a single entity (e.g. an adjacency list) which is more intuitive when the implementation involves a graph.
Alternative 2: Organize all the relationships into a single entity, instead of making them into lists under persons in the address book.
Pros: It is more intuitive to organize all the relationships into a single entity when the implementation involves a graph.
Cons: Maintenance of this single entity of graph can be costly as it can become massive.
Cons: Currently a person is identified by his/her index in the most recent listing. As the indexes of persons change, matching the relationship to the correct persons involved will be a headache.

Aspect: Record of the relationship in the address book
Alternative 1 (current choice): A relationship between two persons are recorded in both persons' UniqueRelationshipList.
Pros: Easy search of the relationship in the address book as both parties involved in the relationship have record of it.
Cons: Maintenance of the relationships is troublesome as a single relationship has to be added, modified or deleted twice.
Alternative 2: A relationship between two persons are recorded in the fromPerson’s `UniqueRelationshipList, except that when the relationship is undirected, it is recorded twice under both parties.
Pros: Easy maintenance of the relationships.
Cons: More scenarios to consider when performing actions to the relationship. Hence, it will lead to more difficult implementation.

Aspect: Persistence mechanism for tag colours
Alternative 1 (current choice): Store in UserPrefs as GUI settings
Pros: Tag colour settings remain the same for different data files, more consistency for user.
Cons: Storage has to be extended to provide access to UserPrefs for Command, difficult to signal a tag colour change when no user data is modified.
Alternative 2: Store in XmlAddressBookStorage as user data.
Pros: Easier to signal tag colour changes to GUI.
Cons: Tag colours will be different depending on which data file is loaded, leading to inconsistency and confusion for the user.

Aspect: Location for storing tag colours
Alternative 1 (current choice): Global tag colour mapping
Pros: No possibility of two identical tags having different colours, easy to update all instances of one tag with new colour.
Cons: More difficult to indicate a tag colour change to the GUI as no user data is visibly modified+ Alternative 2: Each tag stores its own colour.
Pros: Easier to signal tag colour changes to GUI.
Cons: Possibility of identical tag containing different colours.

Aspect: Implementation for deleteRelationship command
Alternative 1 (current choice): The indexes of the persons specified in user input does not matter.
Pros: User only needs to remember the two parties involved in the relationship to be deleted, making this command more user friendly.
Cons: More memory needed for the double record of relationships under both parties involved.
Alternative 2: The indexes of the persons specified in user input matters.
Pros: Less memory needed for recording the relationship.
Cons: User has to know the specific information of the relationship, making this command not user-friendly.

Aspect: Implementation for editRelationship command
Alternative 1 (current choice): The command is implemented internally as deleting an existing relationship and then adding a new relationship with the new name and the new confidence estimate.
Pros: Implementation does not have to access the internal state of a Relationship, and allows for immediate updates to the graph.
Cons: Additional step involved in having to delete and then add a new relationship between the same two persons.
Alternative 2: The command directly accesses and modifies the internal state of a Relationship.
Pros: The command can be completed in a single operation, which may be faster then deleting and adding a new relationship.
Cons: The change cannot be reflected dynamically on the graph after a successful edit.

Aspect: Type of command implemented
Alternative 1 (current choice): editRelationship command extends UndoableCommand instead of Command.
Pros: Users can easily undo their changes if they accidentally update the wrong relationship attribute or have mistakes in the updates (i.e. in the new relationship name/ confidence estimate).
Cons: Additional memory needed for recording the previous stage of the address book.
Alternative 2: editRelationship command extends Command.
Pros: No additional memory needed for recording the previous stage of the address book.
Cons: Users can do another editRelationship command to achieve the undo effect.

Aspect: Implementation for removeTag command
Alternative 1 (current choice): The command is implemented using methods which remove the tag from each person’s tag list.
Pros: Implementation is modular and less dependent on methods used for other commands.
Cons: More tedious to implement since it is not making use of the existing resources such as edit command.
Alternative 2: Adapt current edit command so that removing the tag is done by editing every person’s tag list.
Pros: Making use of existing resources and easier implementation.
Cons: More dependency between commands and the relationship between edit and remove is not clear.

Aspect: Type of command implemented
Alternative 1 (current choice): removeTag command extends UndoableCommand instead of Command.
Pros: Accidental removal of tags can be recovered.
Cons: Additional memory needed for recording the previous stage of the address book.
Alternative 2: removeTag command extends Command.
Pros: No additional memory needed for recording the previous stage of the address book.
Cons: As the removal of Tag is from all the persons in address book, an accidental removal can be disastrous if the user does not intend a complete removal.

Aspect: Removal of the tag from all instead of some by user’s choice
Alternative 1 (current choice): The command currently does not support the removal of a tag from persons specified in the user input.
Pros: Easier implementation since it does not deal with the parsing of more user input.
Cons: The user cannot remove the tags from a few specific people in one command.
Alternative 2: The command allows the user input to specify the persons from whom the tag should be removed.
Pros: The user can remove the tags from a few specific people in one command.
Cons: Implementation is more difficult as parsing of additional user input required. It is also unlikely for user to remove the tag from many persons at once, hence there is a function overlap with edit command.

Aspect: Implementation of modified Dijkstra’s
Alternative 1 (current choice): Extend the current Dijkstra algorithm in the GraphStream library.
Pros: Easy to implement since most of the algorithm is the same, easy to use with graph display.
Cons: Relies on external library for correctness, unable to guarantee correctness of external library.
Alternative 2: Implement modified Dijkstra’s from scratch.
Pros: Can ensure testablity and reliablity of own code, less reliance on external correctness.
Cons: More difficult implementation as it is from scratch, less compatability with graph display means integration between display and algorithm has to be manually written.

Aspect: Access to GraphWrapper from RelPathCommand
Alternative 1 (current choice): Make GraphWrapper a Singleton.
Pros: Easy to access from relPathCommand, no need to modify all commands like if setData() was extended.
Cons: Increases global state.
Alternative 2: Extend Command.setData() to take in GraphWrapper
Pros: Similar to how other components are allowed to interact with commands, better consistency.
Cons: Since the graph display is a GUI component, no straightforward way to have Command access it. Also means that every command’s setData() has to be modified to take into account an external parameter.

Aspect: Implementation for enhanced find command
Alternative 1 (current choice): Adapt current FindCommand and add new predicates for each new type of search.
Pros: Easier to implement since we can reuse existing resources such as ArgumentTokenizer used in add command.
Cons: Implementation is less modular.
Alternative 2: Add a new subclass inheriting from FindCommand for each new type of search.
Pros: Implementation is more modular, and developers can update code more easily.
Cons: More tedious to implement since we cannot make use of existing resources such as ArgumentTokenizer used in add command.

Aspect: Type of command implemented
Alternative 1 (current choice): find command inherits from Command instead of UndoableCommand.
Pros: Easier to implement since we do not need to keep track of previous searches.
Cons: User has to retype all search fields if user wants to repeat a particular search.
Alternative 2: find command inherits from UndoableCommand.
Pros: find becomes undoable, and user can repeat a find easily by undoing the command.
Cons: It is unlikely that a user will repeat a find multiple times in a short period of time, rendering this option somewhat unnecessary.

Aspect: User input for narrowed search field in enhanced find command
Alternative 1 (current choice): Parse prefix in user input to narrow the search to a particular aspect (e.g. n/).
Pros: Easier for user for learn command since it is similar to the add command format.
Cons: Must remember exact prefix for each search field (i.e. /n, /p, /e, /a, /t).
Alternative 2: Parse full keywords in user input to narrow the search to a particular aspect (e.g. name/).
Pros: More intuitive for users as they can simply type what they want to look for.
Cons: User has to type longer commands.

Aspect: Scope of narrowed search
Alternative 1 (current choice): Users can only search within a single narrowed field, or must search through all possible fields (e.g. cannot search for names and emails only).
Pros: Easier to implement, parser only needs to check for a single prefix type and create corresponding predicate for the prefix type.
Cons: Fewer search choices available for users.
Alternative 2: Users can search within an arbitrary number of narrowed fields (e.g. can search for names and emails only, or search for names, emails, and addresses).
Pros: More search options available for users, more advanced search functions.
Cons: Harder to implement since the parser will have to handle more prefixes.

Aspect: Implementation of UndoableCommand
Alternative 1 (current choice): Add a new abstract method executeUndoableCommand()
Pros: We will not lose any undone/redone functionality as it is now part of the default behaviour. Classes that deal with Command do not have to know that executeUndoableCommand() exist.
Cons: Hard for new developers to understand the template pattern.
Alternative 2: Just override execute()
Pros: Does not involve the template pattern, easier for new developers to understand.
Cons: Classes that inherit from UndoableCommand must remember to call super.execute(), or lose the ability to undo/redo.

Aspect: How undo & redo executes
Alternative 1 (current choice): Saves the entire address book.
Pros: Easy to implement.
Cons: May have performance issues in terms of memory usage.
Alternative 2: Individual command knows how to undo/redo by itself.
Pros: Will use less memory (e.g. for delete, just save the person being deleted).
Cons: We must ensure that the implementation of each individual command are correct.

Aspect: Type of commands that can be undone/redone
Alternative 1 (current choice): Only include commands that modifies the address book (add, clear, edit).
Pros: We only revert changes that are hard to change back (the view can easily be re-modified as no data are lost).
Cons: User might think that undo also applies when the list is modified (undoing filtering for example), only to realize that it does not do that, after executing undo.
Alternative 2: Include all commands.
Pros: Might be more intuitive for the user.
Cons: User have no way of skipping such commands if he or she just want to reset the state of the address book and not the view.
Additional Info: See our discussion here.

Aspect: Data structure to support the undo/redo commands
Alternative 1 (current choice): Use separate stack for undo and redo
Pros: Easy to understand for new Computer Science student undergraduates to understand, who are likely to be the new incoming developers of our project.
Cons: Logic is duplicated twice. For example, when a new command is executed, we must remember to update both HistoryManager and UndoRedoStack.
Alternative 2: Use HistoryManager for undo/redo
Pros: We do not need to maintain a separate stack, and just reuse what is already in the codebase.
Cons: Requires dealing with commands that have already been undone: We must remember to skip these commands. Violates Single Responsibility Principle and Separation of Concerns as HistoryManager now needs to do two different things.

Aspect: Implementation of enhanced addCommand
Alternative 1 (current choice): Add new parser methods parseAddPhone, parseAddEmail and parseAddAddress
Pros: Able to isolate the behaviour of the add command and the edit command so that editing an existing Person will not overwrite the fields that should not be edited.
Cons: More difficult to implement as more test cases has to be added for the new parser methods.
Alternative 2: Modify existing parser method parsePhone, parseEmail and parseAddress
Pros: Easier to implement as we can re-use existing tests and codes and just add minor modifications
Cons: The behaviour of edit command overlaps with the behaviour of the add command, causing unintended overwrite of other fields such as address when we don’t want to.

Aspect: Implement separate remark instead of modifying tag
Alternative 1 (current choice): Create a new separate remark command
Pros: Able to provide a cleaner user interface and experience. Also reduces complications in modifying existing working tag system.
Cons: More work has to be done in testing and creating a new command.
Alternative 2: update the tag to accept sentences for remarks
Pros: Easy to implement as we do not need to add a new command.
Cons: The Tag may be more difficult to find and more work is needed to change the find tag command. Additionally, the user interface of tag command also needs to be changed to accommodate long tags.

Aspect: Defining a valid remark input
Alternative 1 (current choice): No restrictions on the kind of remark input the user can put into the addressbook, i.e. the user can put in any characters in any format.
Pros: More freedom for the user as the user can type in anything for adding a remark. It is also easier to implement as the input string does not have to go through other checks.
Cons: Can get messy if the user is not consistent in the way they place in remarks. The sort command applied under remarks also does not sort the remark as well if the input is not consistent.
Alternative 2: Impose a restriction on remarks in the format [Remark Type] remark followed by restriction of only allowing alphabets.
Pros: . The sort remark command will be able to organise and sort the remark better since each remarks are predefined at the start in the [Remark Type].
Cons: . More difficult to implement as we need additional checks to be placed for the restrictions and also less freedom for the user as they need to follow stricter rules before putting in a remark entry.

Aspect: Implementation of sort command
Alternative 1 (current choice): Integrate the various sort types ( by name, phone, email, address, remark) into a single command
Pros: Easier to implement and more straight forward for the user.
Cons: More standardised and less customizable sort since all the various sort types sorts by alphanumeric values in their corresponding ASCII values.
Alternative 2: Have a separate command for each sort types
Pros: More customizable sort as each different sort type can take in different parameters. For example, the address sort can request for parameters to sort by address number and street name.
Cons: More difficult to implement and less user friendly as user have to key in more parameters and remember more things before sorting.

Aspect: Type of clearHistory command
Alternative 1 (current choice): Command
Pros: History is permanently cleared.
Cons: Impossible to undo accidental clearing of history, meaning all undoable changes become permanent.
Alternative 2: UndoableCommand
Pros: Possible to undo accidental clearing of history.
Cons: Since the most likely use for clearHistory is for it to be permanent, having it be undoable is counterintuitive to user expectations.

Aspect: Behaviour of clearHistory command on empty history
Alternative 1 (current choice): Clear anyway and indicate success
Pros: Simple to implement, no additional cases to take care of.
Cons: May be confusing to declare an empty history cleared.
Alternative 2: Indicate that history is empty.
Pros: Clearer messages about the state of the command history.
Cons: More complex to implement, and the end result of clearing an empty history also results in a cleared history, meaning the user intention of clearing their history is fufilled regardless of which alternative is chosen.