Labi Trisha Angelica Vergara - Project Portfolio

PROJECT: SHOCO

Overview

SHOCO is a desktop application used for managing and planning of shopping lists and budgets. Users interact with it through the use of a command-line interface (CLI), the program is written in Java and has bout 5 kLoC.

Summary of Contributions

• Major enhancement 1: Included the ability to edit items in the shopping list.
  • What it does: Allows the user to update values of an item in the shopping list. Such values include the description, price and quantity of an item.
  • Justification: This feature improves the product significantly because a user may make mistakes when adding an item (e.g typos made) and the app should provide a convenient way to rectify such mistakes.
  • Highlights: This enhancement allows the user to update any value of an item as the edit command does not require any order in its input (e.g alphabetical ordering of delimiters).

• Minor enhancement 1: Negative values entered for price and quantity are not accepted. This is for a realistic approach as items will never have negative prices and/or quantities in a real life scenario.

• Major enhancement 2: Added the help function for the SHOCO application.
  • What it does: Lists all acceptable commands, their purpose, valid parameters and examples of usage.
  • Justification: This feature improves the product significantly because the user may forget how certain functions work and so, the app should provide a convenient way for them to check on the accepted command format. With the help feature embedded in the application, users need not solely rely on the SHOCO User Guide for help when they are in doubt.
  • Highlights: This enhancement includes examples of command usages which makes the accepted command formats much more comprehensible to the user.

• Code contributed: [Functional code]

• Other contributions:
  • Project Management:
    • Closed milestones v1.0 and v2.1 on GitHub
    • Assigned bugs and PRs to respective team members on GitHub. (Issues #145-#162)
  • Enhancements to existing features:
    • Included test cases for all commands in input.txt file (Pull Request #69)
    • Added SHOCO logo for the application (Pull request #88)
    • Changed original list display to pretty-printing in a table (Reused code from logicbig) (Pull request #54)
  • Documentation:
    • Added a navigable table of contents and “back to top” links for both SHOCO user guide and developer guide: #111 , #112 , #122
    • Organized the “skeletal” base of the DG in order to provide the team with allocated sections for easier collaboration #114
    • Standardized colour and font of all diagrams in the DG for comprehensibility #191 , #210
    • Added the Manual Testing Section of the DG #204
  • Community:
    • PRs reviewed (with non-trivial review comments): #38 , #169
  • Beyond the project team:
    • Reported feature flaws, documentation bugs and functionality bugs of varying severity for other project teams. (Pull requests #1 - #6)

Contributions to the User Guide

Given below are sections that I have contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Table of Contents

• 1. Introduction
• 2. Quick Start
• 3. Features
  • 3.1 Adding an item: ADD
  • 3.2 Editing an item: EDIT
  • 3.3 Deleting an item: DEL
  • 3.4 Finding an item: FIND
  • 3.5 Marking an item as bought: MARK
  • 3.6 Un-marking a marked item: UNMARK
  • 3.7 Displaying list and budget details: DISPLAY
  • 3.8 Setting a budget: SET
  • 3.9 Resetting a budget: RES
  • 3.10 Clearing the list: CLEAR
  • 3.11 Viewing help: HELP
  • 3.12 Exiting the Program: BYE
• 4. Additional information
• 5. FAQ
• 6. Command Summary

Editing an item: EDIT

Edits the specified item in the shopping list.

Format: EDIT INDEX [i/DESCRIPTION] [p/PRICE] [q/QUANTITY]

• Edits the item at the specified INDEX. The INDEX refers to the index number shown in the displayed shopping list.
• You can view an item’s INDEX number by using the DISPLAY command. More info here.
• The INDEX and [QUANTITY] must be a positive number. e.g 1, 2, 3 ..
• The [PRICE] must be in positive numerical form (decimal form accepted).
• At least one of the three parameters (description/price/quantity) must be present in the command.

  Note: You can rearrange the delimiters i/, p/ , q/ in any order. e.g i/.. p/.. q/.. or q/.. i/.. p/...

Examples of usage:

1. EDIT 3 i/potato p/5.00 q/3
   • Edits the description, price and quantity of the 3rd item in the shopping list
2. EDIT 3 i/potato chips p/5.00 OR EDIT 3 i/potato chips q/2 OR EDIT 3 p/5.00 q/2
   • Edits the description and price / description and quantity / price and quantity of the 3rd item in the shopping list
3. EDIT 3 i/potato chips OR EDIT 3 p/5.00 OR EDIT 3 q/2
   • Edits only description / only price / only quantity of the 3rd item in the shopping list

Viewing help: HELP

Shows the available commands, their purpose and how they are to be used.

Format: HELP

Command Summary

• Add item ADD i/DESCRIPTION [p/PRICE] [q/QUANTITY]
• Edit item EDIT INDEX [i/DESCRIPTION] [p/PRICE] [q/QUANTITY]
• Delete item DEL INDEX
• Find item FIND KEYWORD
• Mark item MARK INDEX
• Un-mark item UNMARK INDEX
• Display list and budget details DISPLAY
• Set budget SET b/AMOUNT
• Reset budget RES
• Clear list CLEAR
• View help HELP
• Exit program BYE

Contributions to the Developer Guide

Given below are sections that I have contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Table of Contents

• 1. Introduction
• 2. Overview of the SHOCO application
• 3. Implementation
  • 3.1 View help feature
  • 3.2 Display feature
  • 3.3 Set budget feature
  • 3.4 Add feature
  • 3.5 Edit feature
  • 3.6 Mark and Unmark feature
  • 3.7 Find feature
  • 3.8 Delete feature
  • 3.9 Clear list feature
  • 3.10 Reset budget feature
  • 3.11 Exit program feature
• Appendix A: Product Scope
• Appendix B: User Stories
• Appendix C: Non-Functional Requirements
• Appendix D: Instructions for Manual Testing
  • Launch and Shutdown
  • Set and Reset a budget
  • Add and Edit an item
  • Mark and Un-Mark an item
  • Find and Delete an item
  • Display and Clear the shopping list

3.2 Edit feature

3.2.1 Current implementation

The edit feature is implemented using an EditCommand class. This class extends from the main Command class. The Item object to be edited is identified by the index number provided in the user input. In addition to the index number, the user input must also contain at least one of these parameters: description, price, quantity.

The process is as follows:

1. Duke class receives user input from the Ui class.
2. A Parser object is created.
3. Duke calls Parser#parseCommand() method to instantiate an EditCommand object based on the user input.
4. Duke class calls the EditCommand#execute() method.
5. In the EditCommand#execute() method, the Item object is retrieved through ShoppingList#getItem(). The original description / price / quantity of the item is overwritten with the new values from the user input through the use of the Item class setter methods.
6. The Item object with its new values is stored back to the ShoppingList object.

The following sequence diagram below shows how the edit feature works. The details of updating the values of an item have been omitted from the diagram. Those details are shown in a separate sequence diagram.

The separate sequence diagram below shows how an item is updated with new values.

3.2.2 Design considerations

Aspect: Data structure to support the edit feature

• Alternative 1 (current choice): Only parameters present in user input are treated as values to update.

  • Pros: User has the flexibility to choose which variables he/she wishes to update.

  • Cons: Might significantly increase the code base as there is a need to check for the presence of the variable in user input.

• Alternative 2: Require all values of an Item object to be updated and parameters must be in alphabetical order.

  • Pros: Will have less code to deal with having no additional parsing of the input string.

  • Cons: Less user flexibility; user must input all parameters even if he/she does not wish to update certain variables.

Reason for choosing alternative 1: By allowing users to update any values they want, it provides them with greater convenience and freedom as they do not need to follow strict command “rules/order”. Furthermore, having greater freedom on input values makes it a hassle-free process for the users.

3.10 View help feature

3.10.1 Current implementation

The help feature is implemented using a HelpCommand class which extends the main Command class. The HelpCommand class shows the program usage instructions to the user.

The process is as follows:

1. Duke receives user input from Ui.
2. Duke calls Parser#parseCommand(). If the user input fails to match any of the correct command keywords (ADD, EDIT, DEL etc.), or if the input matches the HELP command keyword, a HelpCommand object will be instantiated.
3. Duke calls HelpCommand#execute().
4. HelpCommand#execute() lists all the accepted command format SHOCO recognizes, their purpose and 1 or more examples of usage.

The following sequence diagram below shows how the help feature works. Note, the Ui class is omitted in the sequence diagram to emphasise on the other classes:

3.10.2 Design considerations

Aspect: Data structure to support the help feature

• Alternative 1 (current choice): Object-oriented style with a separate class for HelpCommand

  • Pros: Easy to add the help feature without having to change the logic of the code much as each command object is treated as a black box

  • Cons: Might significantly increase the code base with another class being added

• Alternative 2: Implement help feature in the Duke or Parser class

  • Pros: Will have less code to deal with as a new function is simply created in the Duke class

  • Cons: Code becomes less organised since for every other command that we have implemented, Duke class simply executes those commands as black boxes, without worrying about their internal details

Reason for choosing alternative 1: By abstracting out different command types as separate classes, we could work better in parallel and also be able to spot bugs more easily as each class deals with a different functionality

Appendix D: Instructions for Manual Testing

Note: These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

Launch and Shutdown

1. Initial launch

   i. Download the latest version of SHOCO, named CS2113T-T13-1.Shoco.jar under version 2.1.

   ii. Copy it into an empty folder on your desktop.

   iii. While inside the empty folder, open a command prompt window by typing CMD in the address bar of the folder.

   iv. Run the following command in the command prompt window: java -jar CS2113T-T13-1.Shoco.jar

   v. If the font size of the command window is too big, you can decrease it by CTRL + scroll down on your mouse.

    Expected: Shows a welcome message from SHOCO.
   

    

2. Shutdown

   i. Enter the command BYE to exit the SHOCO application.

    Expected: The program is terminated.
   

    

Set and Reset a budget

1. Set a budget

   i. Test case: SET b/500.00

   Expected: Budget is set to $500.00
   

    

   ii. Test case: SET b/10000

    Expected: Budget is set to $5000.00, which is the maximum budget SHOCO allows.
   

    

   iii. Test case: SET b/-100

    Expected: Budget is reset to $0.00, which is the minimum budget SHOCO allows.
   

    

   iv. Other incorrect set budget commands to try: SET b/xxx (where xxx is not a number).

    Expected: An error message and the correct usage of the SET command is shown.
   

    

2. Reset the budget

   i. Test case: RES

    Expected: Budget has been reset to $0.00
   

    

   ii. Other incorrect reset budget commands to try: RES xxx (where xxx is not a number).

    Expected: An error message and the correct usage of the RES command is shown.
   

    

Add and Edit an item

1. Add an item

   Tip: Before adding an item, you can run the DISPLAY command to prevent entering a duplicate description

   i. Test case: ADD i/apple p/3.00 q/2

   Expected: An item with the description - "apple", price - "$3.00" and quantity - "2"  is added.
   

   Tip: You can run the DISPLAY command to check the newly added item.

    

   ii. Test case: ADD p/3.00

    Expected: No item is added. Error message and a correct usage of the ADD command is shown.
   

    

   iii. Other incorrect ADD commands to try: ADD, ADD p/xxx, ADD q/xxx (where xxx is not a number).

    Expected: Similar to previous. 
   

    

2. Edit an item

   Tip: You can run the DISPLAY command to check if the item has been correctly updated.

   Assumption: Valid index and description is provided. (No duplicate description allowed)

   i. Test case: EDIT 1 i/banana

    Expected: The description of the first item is updated to "banana". 
   

    

   ii. Test case: EDIT 1 p/5.60

    Expected: The price of the first item is updated to "$5.60". 
   

    

   iii. Test case: EDIT 1 q/3

    Expected: The quantity of the first item is updated to "3". 
   

    

   iv. Other incorrect edit commands to try: EDIT p/xxx , EDIT q/xxx. (where xxx is not a number).

    Expected: An error message and the correct usage of the EDIT command is shown.
   

    

Find and Delete an item

1. Find an item based on keyword

   i. Test case: FIND apple

   Expected: A list of items that contains "apple" in their description is displayed.
   

    

   ii. Test case: FIND xxx (where xxx is a keyword that is unmatched)

    Expected: An error message and the correct usage of the FIND command is shown.
   

    

2. Delete an item

   Tip: You can run the DISPLAY command to check the index of an item.

   i. Test case: DEL 1

   Expected: The first item (if it exists), is deleted.
   

    

   ii. Test case: DEL xxx (where xxx is a not a number / the item does not exist yet)

    Expected: An error message and the correct usage of the DEL command is shown.
   

    

Display and Clear the shopping list

1. List all items in the shopping list

   i. Test case: DISPLAY

    Expected: A list of all the items and the current budget amount is displayed.
   

    

2. Clear all items in the shopping list

   i. Test case: CLEAR

    Expected: The shopping list is cleared.