[AB3: Tracing Code] Introduce a quick high level overview of AB3

[UdhayaShan1]

Current

The tutorial introduces a architecture diagram and a high level sequence diagram. Afterwards it links to a developer guide.

Problem

Students may be overwhelmed by the information in developer guide and hence may not retain much. They may also forego reading it at all.

Proposed

Instead of immediately directing students to the developer guide, start with a brief, guided overview of the essential component interactions. This overview will set the context for understanding the tracing code and make it easier for students to follow along.

Specifically,

• Discuss the lower-level sequence diagram, with the added UI component (attached image).

  

• We can retain the other integration of diagrams in the tracing code however.

Feedback appreciated thanks!

[damithc]

@UdhayaShan1 The idea is to get the reader to refer corresponding DG sections as she traces the code through each component of AB3. I've made that a bit more clear in this version of the tutorial.

Have a look and see if further improvements can be done. For example,

1. Move a specific DG cross-reference to an earlier/later location
2. Cite more DG diagrams in the tutorial
3. Add more details/diagrams to the DG and then cite them in the tutorial
4. Add more diagrams to the tutorial

[UdhayaShan1]

Thanks Prof

Possibly,

1. I think under Setting a breakpoint, the more specific sequence diagram can be used/added instead. Idea is for this diagram to overarch the debugging flow. As they debug they can relate to the diagram with aid of headers as in #17
2. Continue citing this diagram with arrows to show which part of the debugging stage we are at.
3. If possible, add sequence diagrams with exceptions but this might be out of syllabus

[damithc]

1. I think under Setting a breakpoint, the more specific sequence diagram can be used/added instead. Idea is for this diagram to overarch the debugging flow. As they debug they can relate to the diagram with aid of headers as in [AB3: Tracing Code] Add more headers to section instructions #17

@UdhayaShan1 You can propose diagram(s) that match that idea. But ensure no diagram shows low level details of more than one component. A diagram showing low level details of multiple components goes against the top-down approach to describing the design. For example, the diagram in https://github.com/se-edu/guides/issues/16#issue-2370332580 is fine because it shows low-level detail of the Logic component only.

Also, it is important that we use this opportunity to get the student to read through the DG. Otherwise they will only read the DG when they have to update it (i.e., towards the end of the project), which defeats the purpose of its existence (the DG is meant to help new developers understand the design). So, it is better to add more diagrams to the DG and refer to them in the tutorial rather than create an alternative version of the DG in this tutorial.

[UdhayaShan1]

Thanks! In addition, since we have discussed low level of Logic and traced it, if execute is called..

@Override
public CommandResult execute(Model model) throws CommandException {
    ...
    Person personToEdit = lastShownList.get(index.getZeroBased());
    Person editedPerson = createEditedPerson(personToEdit, editPersonDescriptor);
    if (!personToEdit.isSamePerson(editedPerson) && model.hasPerson(editedPerson)) {
        throw new CommandException(MESSAGE_DUPLICATE_PERSON);
    }
    model.setPerson(personToEdit, editedPerson);
    model.updateFilteredPersonList(PREDICATE_SHOW_ALL_PERSONS);
    return new CommandResult(String.format(MESSAGE_EDIT_PERSON_SUCCESS, editedPerson));
}

Is it a good idea to add sequence diagram to explain the low-level of Model now seperately? Can add this to DG possibly under Model component, currently it just has a class diagram.

[UdhayaShan1]

Also we are stepping over the execute statements, is it necessary to continue debugging by stepping into them to appreciate the Model component better?

[damithc]

Is it a good idea to add sequence diagram to explain the low-level of Model now seperately? Can add this to DG possibly under Model component, currently it just has a class diagram.

@UdhayaShan1 Sure, we can try that.

Also we are stepping over the execute statements, is it necessary to continue debugging by stepping into them to appreciate the Model component better?

Not sure, We have to think from the student point of view and decide. Jumping between components can make things harder to understand too. So, one approach is to do two passes. In the first pass, step-over most method calls just to get a quick idea about the flow, but in the second pass, step-into more method calls to get a more detailed understanding.