diff --git a/tutorials/ab3TracingCode.md b/tutorials/ab3TracingCode.md index 25cbf83a..07d0c027 100644 --- a/tutorials/ab3TracingCode.md +++ b/tutorials/ab3TracingCode.md @@ -7,7 +7,6 @@ pageNav: 3 # {{ title }} - > Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write. > > — Robert C. Martin Clean Code: A Handbook of Agile Software Craftsmanship @@ -105,30 +104,66 @@ Now let’s set the breakpoint. First, double-click the item to reach the corres ## Tracing the execution path -Recall from the User Guide that the `edit` command has the format: `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…` For this tutorial we will be issuing the command `edit 1 n/Alice Yeoh`. +For this code tracing, +we will explore the `EditCommand` which is a feature that allows users to edit exising person fields in AB3. + + + Recall from the User Guide that the edit command has the format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…. + + +For this tutorial, we will be issuing the command edit 1 n/Alice Yeoh + +At this point, you should have understood the high-level overview of the sequence diagram which shows the general execution flows between the main components [**shown above**](##setting-a-breakpoint). + +We will begin to trace the following sequence diagram which explores the `Logic` component in more detail which will be paramount to understanding other commands as well! +The diagrams will be reproduced with labels in their sections to highlight the pass of control between classes. + +Some of the labels can be clicked on to view additional description of the execution flow. +Try it out in the sequence diagram below! + + + + **Tip:** Over the course of the debugging session, you will encounter every major component in the application. Try to keep track of what happens inside the component and where the execution transfers to another component. +### 1. MainWindow -> LogicManager + + + + + 1. To start the debugging session, simply `Run` \> `Debug Main` {{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Running the code in debugger mode**", "intellijDebugger.md#intellij-debugger-mode", indent=1) }} -2. When the GUI appears, enter `edit 1 n/Alice Yeoh` into the command box and press `Enter`. +1. When the GUI appears, enter `edit 1 n/Alice Yeoh` into the command box and press `Enter`. -3. The Debugger tool window should show up and show something like this:
+1. The Debugger tool window should show up and show something like this:
![DebuggerStep1](images/tracing/DebuggerStep1.png) {{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Examining the state of the suspended program**", "intellijDebugger.md#intellij-debugger-examining-state", indent=1) }} -4. Use the _Show execution point_ feature to jump to the line of code that we stopped at (which should be - `CommandResult commandResult = logic.execute(commandText);`{.java}, as that is where we put the breakpoint). +1. Use the _Show execution point_ feature to jump to the line of code that we stopped at (which should be + `CommandResult commandResult = logic.execute(commandText);`, as that is where we put the breakpoint). {{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Show execution point**", "intellijDebugger.md#show-execution-point", indent=1) }} -5. We are interested in the `logic.execute(commandText)` portion of that line so let’s _Step in_ into that method call:
+1. We are interested in the `logic.execute(commandText)` portion of that line so let’s _Step in_ into that method call:
{{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Stepping into a method**", "intellijDebugger.md#intellij-debugger-step-into", indent=1) }} -6. We end up in `LogicManager#execute()` (not `Logic#execute` -- but this is expected because we know the `execute()` method in the `Logic` interface is actually implemented by the `LogicManager` class). Let’s take a look at the body of the method. Given below is the same code, with additional explanatory comments. +### 2. LogicManager -> AddressBookParser + + + + + + +1. After stepping in, we note that `MainWindow` has passed control to the `Logic` component. + +1. Specifically, we end up in `LogicManager#execute()` + * Not `Logic#execute` -- but this is expected because we know the `execute()` method in the `Logic` interface is actually implemented by the `LogicManager` class. +1. Let’s take a look at the body of the method. Given below is the same code, with additional explanatory comments. **LogicManager\#execute().** @@ -158,12 +193,13 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ } ``` -7. `LogicManager#execute()` appears to delegate most of the heavy lifting to other components. Let’s take a closer look at each one. +1. `LogicManager#execute()` appears to delegate most of the heavy lifting to other components. Let’s take a closer look at each one. -8. _Step over_ the logging code since it is of no interest to us now. +1. _Step over_ the logging code since it is of no interest to us now. {{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Stepping through the code**", "intellijDebugger.md#intellij-debugger-step-through", indent=1) }} -9. _Step into_ the line where user input is parsed from a String to a Command, which should bring you to the `AddressBookParser#parseCommand()` method (partial code given below): +1. _Step into_ the line where user input is parsed from a String to a Command, which should bring you to the `AddressBookParser#parseCommand()` method (partial code given below): + ```java public Command parseCommand(String userInput) throws ParseException { ... @@ -172,12 +208,21 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ ... ``` -10. _Step over_ the statements in that method until you reach the `switch` statement. The 'Variables' window now shows the value of both `commandWord` and `arguments`:
- ![Variables](images/tracing/Variables.png) +### 3. AddressBookParser -> EditCommandParser + + + + + + +1. Now, `LogicManager` has passed control to `AddressBookParser` + +1. _Step over_ the statements in that method until you reach the `switch` statement. The 'Variables' window now shows the value of both `commandWord` and `arguments`:
+ ![Variables](images/tracing/VariablesAnnotated.png) -11. We see that the value of `commandWord` is now `edit` but `arguments` is still not processed in any meaningful way. +1. We see that the value of `commandWord` is now `edit` but `arguments` is still not processed in any meaningful way. -12. Stepping through the `switch` block, we end up at a call to `EditCommandParser().parse()` as expected (because the command we typed is an edit command). +1. Stepping through the `switch` block, we end up at a call to `EditCommandParser().parse()` as expected (because the command we typed is an edit command). ```java ... @@ -186,7 +231,21 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ ... ``` -13. Let’s see what `EditCommandParser#parse()` does by stepping into it. You might have to click the 'step into' button multiple times here because there are two method calls in that statement: `EditCommandParser()` and `parse()`. +1. `EditCommandParser` is created first, annotated with [label T3](#3-addressbookparser-editcommandparser) + +1. `AddressBookParser` now calls `parse(...)` of the newly created `EditCommandParser`, highlighted in the diagram as well, passing control to + `EditCommandParser`, annotated with [label T4](#3-addressbookparser-editcommandparser) + + +### 4. EditCommandParser -> EditCommand + + + + + + + +1. Let’s see what `EditCommandParser#parse()` does by stepping into it. You might have to click the 'step into' button multiple times here because there are two method calls in that statement: `EditCommandParser()` and `parse()`. @@ -194,20 +253,32 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ {{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Stepping out of a method**", "intellijDebugger.md#intellij-debugger-step-out", indent=1) }} -14. Stepping through the method shows that it calls `ArgumentTokenizer#tokenize()` and `ParserUtil#parseIndex()` to obtain the arguments and index required. +1. Stepping through the method, `EditCommandParser#parse()`, shows that it calls `ArgumentTokenizer#tokenize()` and `ParserUtil#parseIndex()` to obtain the arguments and index required. + +1. The rest of the method seems to exhaustively check for the existence of each possible parameter of the `edit` command and store any possible changes in an `EditPersonDescriptor`. Recall that we can verify the contents of `editPersonDesciptor` through the 'Variables' window.
+ ![EditCommand](images/tracing/EditCommandAnnotated.png) -15. The rest of the method seems to exhaustively check for the existence of each possible parameter of the `edit` command and store any possible changes in an `EditPersonDescriptor`. Recall that we can verify the contents of `editPersonDesciptor` through the 'Variables' window.
- ![EditCommand](images/tracing/EditCommand.png) +1. Note the index and the contents of `EditPersonDescriptor`. In this case, since the argument contains only name, only the `Name` field of `EditPersonDescriptor` is set. -16. As you just traced through some code involved in parsing a command, you can take a look at this class diagram to see where the various parsing-related classes you encountered fit into the design of the `Logic` component. - +1. A `EditCommand` with parsed index and created `EditPersonDescriptor` from the parsed arguments is created and returned, annotated with [label T5](#4-editcommandparser-editcommand). -17. Let’s continue stepping through until we return to `LogicManager#execute()`. +1. The newly created `EditCommand` is returned to `AddressBookParser` which then returns to `LogicManager`, returning control to `LogicManager`. This is annotated with [label T6 and T7](#4-editcommandparser-editcommand). - The sequence diagram below shows the details of the execution path through the Logic component. Does the execution path you traced in the code so far match the diagram?
- +---- -18. Now, step over until you read the statement that calls the `execute()` method of the `EditCommand` object received, and step into that `execute()` method (partial code given below): +As you just traced through some code involved in parsing a command, you can take a look at this class diagram to see where the various parsing-related classes you encountered fit into the design of the `Logic` component. + + +### 5. LogicManager -> EditCommand + + + + + + +1. Let’s continue stepping through until we return to `LogicManager#execute()`. + +1. Step over until you read the statement that calls the `execute()` method of the `EditCommand` object received, and step into that `execute()` method (partial code given below): **`EditCommand#execute()`:** ```java @@ -225,7 +296,7 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ } ``` -19. As suspected, `command#execute()` does indeed make changes to the `model` object. Specifically, +1. As suspected, `command#execute()` does indeed make changes to the `model` object. Specifically, * it uses the `setPerson()` method (defined in the interface `Model` and implemented in `ModelManager` as per the usual pattern) to update the person data. * it uses the `updateFilteredPersonList` method to ask the `Model` to populate the 'filtered list' with _all_ persons.
FYI, The 'filtered list' is the list of persons resulting from the most recent operation that will be shown to the user immediately after. For the `edit` command, we populate it with all the persons so that the user can see the edited person along with all other persons. If this was a `find` command, we would be setting that list to contain the search results instead.
@@ -233,22 +304,25 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
* {{ dg_ref }} This is a good time to read through the [**_Model component_** section of the DG](https://se-education.org/addressbook-level3/DeveloperGuide.html#model-component) -20. As you step through the rest of the statements in the `EditCommand#execute()` method, you'll see that it creates a `CommandResult` object (containing information about the result of the execution) and returns it.
- Advancing the debugger by one more step should take you back to the middle of the `LogicManager#execute()` method.
+1. As you step through the rest of the statements in the `EditCommand#execute()` method, you'll see that it creates a `CommandResult` object (containing information about the result of the execution) and returns it to `LogicManager`.
-21. Given that you have already seen quite a few classes in the `Logic` component in action, see if you can identify in this partial class diagram some of the classes you've encountered so far, and see how they fit into the class structure of the `Logic` component: +1. Advancing the debugger by one more step should take you back to the middle of the `LogicManager#execute()` method.
+ +1. Given that you have already seen quite a few classes in the `Logic` component in action, see if you can identify in this partial class diagram some of the classes you've encountered so far, and see how they fit into the class structure of the `Logic` component: * {{ dg_ref }} This is a good time to read through the [**_Logic component_** section of the DG](https://se-education.org/addressbook-level3/DeveloperGuide.html#logic-component) -22. Similar to before, you can step over/into statements in the `LogicManager#execute()` method to examine how the control is transferred to the `Storage` component and what happens inside that component. +### 6. LogicManager -> Storage + +1. Similar to before, you can step over/into statements in the `LogicManager#execute()` method to examine how the control is transferred to the `Storage` component and what happens inside that component. {{ embed("[Refresher] Intellij IDEA: Using the debugger -> **Choosing which method to step into**", "intellijDebugger.md#choosing-which-method-to-step-into", indent=1) }} -23. As you step through the code inside the `Storage` component, you will eventually arrive at the `JsonAddressBookStorage#saveAddressBook()` method which calls the `JsonSerializableAddressBook` constructor, to create an object that can be _serialized_ (i.e., stored in storage medium) in JSON format. That constructor is given below (with added line breaks for easier readability): +1. As you step through the code inside the `Storage` component, you will eventually arrive at the `JsonAddressBookStorage#saveAddressBook()` method which calls the `JsonSerializableAddressBook` constructor, to create an object that can be _serialized_ (i.e., stored in storage medium) in JSON format. That constructor is given below (with added line breaks for easier readability): **`JsonSerializableAddressBook` constructor:** ```java @@ -275,6 +349,14 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ * {{ dg_ref }} This is a good time to read through the [**_Storage component_** section of the DG](https://se-education.org/addressbook-level3/DeveloperGuide.html#storage-component) +### 7. Returning to MainWindow + + + + + + + 1. We can continue to step through until you reach the end of the `LogicManager#execute()` method and return to the `MainWindow#executeCommand()` method (the place where we put the original breakpoint). 1. Stepping into `resultDisplay.setFeedbackToUser(commandResult.getFeedbackToUser());`, we end up in: @@ -290,7 +372,6 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [ 1. Finally, you can step through until you reach the end of`MainWindow#executeCommand()`.
{{ dg_ref }} This is a good time to read through the [**_UI component_** section of the DG](https://se-education.org/addressbook-level3/DeveloperGuide.html#ui-component) - ## Conclusion In this tutorial, we traced a valid edit command from raw user input to the result being displayed to the user. From this tutorial, you learned more about how the various components work together to produce a response to a user command. diff --git a/tutorials/images/style.puml b/tutorials/images/style.puml index f7d7347a..b7009bca 100644 --- a/tutorials/images/style.puml +++ b/tutorials/images/style.puml @@ -18,12 +18,14 @@ !define LOGIC_COLOR_T2 #6A6ADC !define LOGIC_COLOR_T3 #1616B0 !define LOGIC_COLOR_T4 #101086 +!define LOGIC_COLOR_T5 #adbc40 !define MODEL_COLOR #9D0012 !define MODEL_COLOR_T1 #F97181 !define MODEL_COLOR_T2 #E41F36 !define MODEL_COLOR_T3 #7B000E !define MODEL_COLOR_T4 #51000A +!define MODEL_COLOR_T5 #c6d4c0 !define STORAGE_COLOR #A38300 !define STORAGE_COLOR_T1 #FFE374 diff --git a/tutorials/images/tracing/EditCommandAnnotated.png b/tutorials/images/tracing/EditCommandAnnotated.png new file mode 100644 index 00000000..543e7fc7 Binary files /dev/null and b/tutorials/images/tracing/EditCommandAnnotated.png differ diff --git a/tutorials/images/tracing/EditSequenceDiagramWithMainWindow.puml b/tutorials/images/tracing/EditSequenceDiagramWithMainWindow.puml new file mode 100644 index 00000000..203521be --- /dev/null +++ b/tutorials/images/tracing/EditSequenceDiagramWithMainWindow.puml @@ -0,0 +1,80 @@ +@startuml +!include ../style.puml +skinparam ArrowFontStyle plain + +box Ui MODEL_COLOR_T5 +participant "m:MainWindow" as MainWindow LOGIC_COLOR_T5 + +box Logic LOGIC_COLOR_T1 +participant ":LogicManager" as LogicManager LOGIC_COLOR +participant ":AddressBookParser" as AddressBookParser LOGIC_COLOR +participant ":EditCommandParser" as EditCommandParser LOGIC_COLOR +participant "d:EditCommand" as EditCommand LOGIC_COLOR +participant "r:CommandResult" as CommandResult LOGIC_COLOR +end box + +box Model MODEL_COLOR_T1 +participant "m:Model" as Model MODEL_COLOR +end box + + + +--> MainWindow +activate MainWindow +MainWindow -> LogicManager : execute("edit 1 n/Alice Yeoh") +activate LogicManager + +LogicManager -> AddressBookParser : parseCommand("edit 1 n/Alice Yeoh") +activate AddressBookParser + +create EditCommandParser +AddressBookParser -> EditCommandParser +activate EditCommandParser + +EditCommandParser --> AddressBookParser +deactivate EditCommandParser + +AddressBookParser -> EditCommandParser : parse("1 n/Alice Yeoh") +activate EditCommandParser + +create EditCommand +EditCommandParser -> EditCommand +activate EditCommand + +EditCommand --> EditCommandParser : +deactivate EditCommand + +EditCommandParser --> AddressBookParser : d +deactivate EditCommandParser +'Hidden arrow to position the destroy marker below the end of the activation bar. +EditCommandParser -[hidden]-> AddressBookParser +destroy EditCommandParser + +AddressBookParser --> LogicManager : d +deactivate AddressBookParser + +LogicManager -> EditCommand : execute(m) +activate EditCommand + +EditCommand -> Model : ... +activate Model + +Model --> EditCommand +deactivate Model + +create CommandResult +EditCommand -> CommandResult +activate CommandResult + +CommandResult --> EditCommand +deactivate CommandResult + +EditCommand --> LogicManager : r +deactivate EditCommand + +LogicManager --> MainWindow +deactivate LogicManager + +[<-- MainWindow +deactivate MainWindow +@enduml diff --git a/tutorials/images/tracing/LogicSequenceDiagram.png b/tutorials/images/tracing/LogicSequenceDiagram.png new file mode 100644 index 00000000..90a9d066 Binary files /dev/null and b/tutorials/images/tracing/LogicSequenceDiagram.png differ diff --git a/tutorials/images/tracing/LogicSequenceDiagram.puml b/tutorials/images/tracing/LogicSequenceDiagram.puml index 42bf46d3..9f8b4055 100644 --- a/tutorials/images/tracing/LogicSequenceDiagram.puml +++ b/tutorials/images/tracing/LogicSequenceDiagram.puml @@ -9,14 +9,18 @@ Participant "command:EditCommand" as ec LOGIC_COLOR [-> logic : execute activate logic -logic -> abp ++: parseCommand(commandText) +logic -> abp ++: parseCommand(edit 1 n/Alice Yeoh) create ecp abp -> ecp -abp -> ecp ++: parse(arguments) +activate ecp +ecp -> abp +deactivate ecp +abp -> ecp ++: parse(1 n/Alice Yeoh) create ec -ecp -> ec ++: index, editPersonDescriptor +ecp -> ec ++: 1, n/Alice Yeoh ec --> ecp -- ecp --> abp --: command abp --> logic --: command +[<-- logic @enduml diff --git a/tutorials/images/tracing/LogicSequenceDiagramImproved.png b/tutorials/images/tracing/LogicSequenceDiagramImproved.png new file mode 100644 index 00000000..b2d33dda Binary files /dev/null and b/tutorials/images/tracing/LogicSequenceDiagramImproved.png differ diff --git a/tutorials/images/tracing/LogicSequenceDiagramImproved.puml b/tutorials/images/tracing/LogicSequenceDiagramImproved.puml new file mode 100644 index 00000000..3b82e231 --- /dev/null +++ b/tutorials/images/tracing/LogicSequenceDiagramImproved.puml @@ -0,0 +1,39 @@ +@startuml +!include ../style.puml +skinparam ArrowFontStyle plain + +Participant ":LogicManager" as logic LOGIC_COLOR +Participant ":AddressBookParser" as abp LOGIC_COLOR +Participant ":EditCommandParser" as ecp LOGIC_COLOR +Participant "command:EditCommand" as ec LOGIC_COLOR + +-> logic : execute("edit 1 n/Alice Yeoh") +activate logic +logic -> abp ++: parseCommand("edit 1 n/Alice Yeoh") +create ecp +abp -> ecp +activate ecp +ecp --> abp +deactivate ecp +abp -> ecp ++: parse("1 n/Alice Yeoh") +create ec +ecp -> ec ++: 1, editPersonDescriptor +ec --> ecp -- +ecp --> abp --: command +ecp -[hidden]-> abp --: command +destroy ecp + + +abp --> logic --: command + +logic -> ec : execute +activate ec +ec --> logic : commandResult +deactivate ec +ec -[hidden]-> logic : commandResult +destroy ec + +<-- logic :commandResult +deactivate logic + +@enduml diff --git a/tutorials/images/tracing/LogicSequenceDiagramOnlyWithMainWindow.png b/tutorials/images/tracing/LogicSequenceDiagramOnlyWithMainWindow.png new file mode 100644 index 00000000..dbcf3a6a Binary files /dev/null and b/tutorials/images/tracing/LogicSequenceDiagramOnlyWithMainWindow.png differ diff --git a/tutorials/images/tracing/LogicSequenceDiagramOnlyWithMainWindow.puml b/tutorials/images/tracing/LogicSequenceDiagramOnlyWithMainWindow.puml new file mode 100644 index 00000000..d9bee5c1 --- /dev/null +++ b/tutorials/images/tracing/LogicSequenceDiagramOnlyWithMainWindow.puml @@ -0,0 +1,16 @@ +@startuml +!include ../style.puml +skinparam ArrowFontStyle plain + +Participant ":MainWindow" as main LOGIC_COLOR +Participant ":LogicManager" as logic LOGIC_COLOR + +main -> logic : execute("edit 1 n/Alice Yeoh") +activate logic + +logic -> : ... +logic <-- : commandResult +logic --> main --: commandResult +deactivate logic + +@enduml diff --git a/tutorials/images/tracing/VariablesAnnotated.png b/tutorials/images/tracing/VariablesAnnotated.png new file mode 100644 index 00000000..df6c1202 Binary files /dev/null and b/tutorials/images/tracing/VariablesAnnotated.png differ