Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[AB3: Tracing Code] Add more headers to section instructions #42

Open
wants to merge 23 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
cb71de9
Edit LogicSequenceDiagram puml to show exact arguments
UdhayaShan1 Jul 7, 2024
6d49bce
Fix LogicSequenceDiagram by showing creation of parser
UdhayaShan1 Jul 7, 2024
16abf00
Add new edit sequence puml with MainWindow and model for future use
UdhayaShan1 Jul 7, 2024
ec55e13
Update tracingcode.md with h3 css style added
UdhayaShan1 Jul 7, 2024
005583c
Merge branch 'master' into tracing-code-add-headers
UdhayaShan1 Jul 7, 2024
464e91a
Edit arguments
UdhayaShan1 Jul 8, 2024
5ad51a5
Fix EditSequenceDiagramWithMainWindow png and remove html anchor
UdhayaShan1 Jul 13, 2024
9212c14
Edit LogicSequence puml to show execution and add annotated images
UdhayaShan1 Jul 13, 2024
a65f636
Add a logic sequence diagram only with mainwindow and logicmanager
UdhayaShan1 Jul 13, 2024
9f8f897
Add remaining headers and diagrams
UdhayaShan1 Jul 13, 2024
2990596
Update image
UdhayaShan1 Jul 13, 2024
4cfab7b
Merge branch 'master' into tracing-code-add-headers
UdhayaShan1 Jul 27, 2024
8fb8f61
Remove redundant lines and custom css
UdhayaShan1 Jul 27, 2024
5fc1be6
Updated tracing code high level sequence diagram description
UdhayaShan1 Jul 27, 2024
da6ae49
Removed MainWindow from puml to not overlap components
UdhayaShan1 Jul 27, 2024
3327fde
Misc change
UdhayaShan1 Jul 27, 2024
122ca7d
Add double quotes for puml method call arguments
UdhayaShan1 Jul 27, 2024
42c96b5
Add label content and change label names to "T<no>" in bold
UdhayaShan1 Jul 27, 2024
66cca5e
Making spacing consistent
UdhayaShan1 Jul 27, 2024
451b0fe
Update label content to be clearer
UdhayaShan1 Jul 27, 2024
e5e4331
Remove unnecessary spacing and fix typos
UdhayaShan1 Jul 27, 2024
e7db74d
Merge branch 'master' into tracing-code-add-headers
UdhayaShan1 Jul 27, 2024
ba92d2f
Added deletion to puml and misc change
UdhayaShan1 Jul 28, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 115 additions & 13 deletions tutorials/ab3TracingCode.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ pageNav: 3

# {{ title }}


<link rel="stylesheet" href="images/tracing/static/tracing.css">
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved
> 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
Expand All @@ -20,7 +20,8 @@ Before we jump into the code, it is useful to get an idea of the overall structu

<pic src="https://se-education.org/addressbook-level3/images/ArchitectureDiagram.png" alt="ArchitectureDiagram" />

It also has a sequence diagram (reproduced below) that tells us how a command propagates through the App.
It also has a sequence diagram (reproduced below)
that tells us how a command propagates through the App.
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved

<pic src="https://se-education.org/addressbook-level3/images/ArchitectureSequenceDiagram.png" width="550" />

Expand Down Expand Up @@ -88,15 +89,45 @@ Bingo\! `MainWindow#executeCommand()` seems to be exactly what we’re looking f
Now let’s set the breakpoint. First, double-click the item to reach the corresponding code. Once there, click on the left gutter to set a breakpoint, as shown below.
![LeftGutter](images/tracing/LeftGutter.png)


UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved
## 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`.
At this point, you should have appreciated the general sequence diagram [**shown above**](#before-we-start)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some questions that might pop up in the reader's mind:

  • What do you mean by 'appreciated'?
  • What is a 'general sequence diagram'?

Missing a full stop.

Copy link
Author

@UdhayaShan1 UdhayaShan1 Jul 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Made it clearer that its high level sequence diagram with all components and general execution flow and shifted it below so we can link to the low level sequence diagram with explores Logic



For this code tracing,
we will explore the `EditCommand` which is a feature that allows users to edit exising person fields in AB3.

<box type="tip" seamless>
Recall from the <a href="https://se-education.org/addressbook-level3/UserGuide.html#editing-a-person--edit">User Guide</a> that the <code>edit</code> command has the format: <code>edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…</code>.
</box>

For this tutorial, we will be issuing the command <code>edit 1 n/Alice Yeoh</code>

Specifically,
we 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.

<puml src="images/tracing/LogicSequenceDiagramWithMainWindow.puml" alt="Tracing an `edit` command with specific arguments"></puml>
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved


<box type="tip" seamless>

**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.
</box>





UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved
### 1. MainWindow -> LogicManager

<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
<!-- Set Legend to both -->
<a-point x="24%" y="16%" label="1"/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we use a different label e.g., t1 to avoid confusing with step numbers in the explanations?

Copy link
Author

@UdhayaShan1 UdhayaShan1 Jul 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure will call it T1

</annotate>

1. To start the debugging session, simply `Run` \> `Debug Main`

1. When the GUI appears, enter `edit 1 n/Alice Yeoh` into the command box and press `Enter`.
Expand All @@ -111,7 +142,17 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
1. We are interested in the `logic.execute(commandText)` portion of that line so let’s _Step in_ into that method call:<br>
![StepInto](images/tracing/StepInto.png)

1. 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

<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
<!-- Set Legend to both -->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<!-- Set Legend to both -->

Also update the alt property

<a-point x="47.5%" y="23%" label="2"/>
</annotate>


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). Let’s take a look at the body of the method. Given below is the same code, with additional explanatory comments.
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved

**LogicManager\#execute().**

Expand Down Expand Up @@ -146,7 +187,8 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
1. _Step over_ the logging code since it is of no interest to us now.
![StepOver](images/tracing/StepOver.png)

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):
1. _Step into_ the line where user input in parsed from a String to a Command, which should bring you to the `AddressBookParser#parseCommand()` method (partial code given below):
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved

```java
public Command parseCommand(String userInput) throws ParseException {
...
Expand All @@ -155,8 +197,20 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
...
```

### 3. AddressBookParser -> EditCommandParser


<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
<!-- Set Legend to both -->
<a-point x="58%" y="26%" label="3"/>
<a-point x="64%" y="44%" label="4"/>
</annotate>


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`:<br>
![Variables](images/tracing/Variables.png)
![Variables](images/tracing/VariablesAnnotated.png)

1. We see that the value of `commandWord` is now `edit` but `arguments` is still not processed in any meaningful way.

Expand All @@ -169,27 +223,60 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
...
```

1. `EditCommandParser` is created first, annotated with [label 3](#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 4](#3-addressbookparser-editcommandparser)
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved


### 4. EditCommandParser -> EditCommand

<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
<!-- Set Legend to both -->
<a-point x="82%" y="51%" label="5"/>
<a-point x="50%" y="64%" color = "RED" label="6"/>
<a-point x="26%" y="71%" color = "RED" label="7"/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spacing around = is not consistent.

</annotate>


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()`.

<box type="tip" seamless>

**Intellij Tip:** Sometimes, you might end up stepping into functions that are not of interest. Simply use the `step out` button to get out of them!
</box>

1. 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.<br>
![EditCommand](images/tracing/EditCommand.png)
![EditCommand](images/tracing/EditCommandAnnotated.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.
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved

1. A `EditCommand` with parsed index and created `EditPersonDescriptor` from the parsed arguments is created and returned, annotated with [label 5](#4-editcommandparser-editcommand).

1. The newly created `EditCommand` is returned to `AddressBookParser` which then returns to `LogicManager`, returning control to `LogicManager`. This is annotated with [label 6 and 7](#4-editcommandparser-editcommand).

----

1. 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.
<pic src="https://se-education.org/addressbook-level3/images/ParserClasses.png" width="600"/>

1. Let’s continue stepping through until we return to `LogicManager#execute()`.

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?<br>
<puml src="images/tracing/LogicSequenceDiagram.puml" alt="Tracing an `edit` command through the Logic component"/>
### 5. LogicManager -> EditCommand

<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
<!-- Set Legend to both -->
<a-point x="90%" y="79%" label="8"/>
<a-point x="26%" y="86.5%" color = "RED" label="9"/>
</annotate>

1. 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):
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
Expand All @@ -215,14 +302,21 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
<pic src="https://se-education.org/addressbook-level3/images/ModelClassDiagram.png" width="450" /><br>
* {{ 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)

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.<br>
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`.<br>


UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved
Advancing the debugger by one more step should take you back to the middle of the `LogicManager#execute()` method.<br>

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:
<pic src="https://se-education.org/addressbook-level3/images/LogicClassDiagram.png" width="550"/>

* {{ 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)


### 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.

<box type="tip" seamless>
Expand Down Expand Up @@ -257,6 +351,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

UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved
<annotate src="images/tracing/LogicSequenceDiagramOnlyWithMainWindow.png" alt="Sample Image">
<!-- Set Legend to both -->
<a-point x="19%" y="84%" color = "RED" label="9"/>
</annotate>

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:
Expand Down
2 changes: 2 additions & 0 deletions tutorials/images/style.puml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to have these png file in the repo. MarkBind will generate it automatically from the puml file with the same name.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
80 changes: 80 additions & 0 deletions tutorials/images/tracing/EditSequenceDiagramWithMainWindow.puml
Original file line number Diff line number Diff line change
@@ -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
Binary file added tutorials/images/tracing/LogicSequenceDiagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 7 additions & 3 deletions tutorials/images/tracing/LogicSequenceDiagram.puml
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
abp -> ecp ++: parse(1 n/Alice Yeoh)
abp -> ecp ++: parse("1 n/Alice Yeoh")

Check other places as well.

create ec
ecp -> ec ++: index, editPersonDescriptor
ecp -> ec ++: 1, n/Alice Yeoh
ec --> ecp --
ecp --> abp --: command
abp --> logic --: command
[<-- logic

@enduml
UdhayaShan1 marked this conversation as resolved.
Show resolved Hide resolved
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions tutorials/images/tracing/LogicSequenceDiagramWithMainWindow.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
@startuml
!include ../style.puml
skinparam ArrowFontStyle plain

Participant ":MainWindow" as main LOGIC_COLOR
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

main -> 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
abp --> logic --: command

logic --> ec : execute
activate ec
ec --> logic : commandResult
deactivate ec

logic --> main --: commandResult

@enduml
Binary file added tutorials/images/tracing/VariablesAnnotated.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions tutorials/images/tracing/static/tracing.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
/* custom.css */
h3 {
color: #ff6347;
padding: 10px;
border-radius: 5px;
}