search

nus-cs2103-AY2324S1 / pe-dev-response

0 stars 0 forks source link

Too many details in the sequence diagram for editing a student #5343

Open nus-se-script opened 10 months ago

nus-se-script commented 10 months ago

Note from the teaching team: This bug was reported during the Part II (Evaluating Documents) stage of the PE. You may reject this bug if it is not related to the quality of documentation.

Screenshot 2023-11-17 at 5.27.02 PM.png Screenshot 2023-11-17 at 5.27.02 PM

Description

There are too many lower level details in the diagram for the interaction between the model and the EditStudentCommand. This also makes it hard for the reader to read.

Justification This makes it hard for the reader to read. Perhaps you can emulate the RemoveStudentCommand sequence diagram to increase readability and consistency of the sequence diagrams throughout the DG.

[original: nus-cs2103-AY2324S1/pe-interim#4923] [original labels: severity.Low type.DocumentationBug]

revdrag commented 10 months ago

Team's Response

Justification for rejection of bug:

The method calls on Model by EditStudentCommand are specifically chosen to be in the diagram as they are necessary, omitting details that would have otherwise make it cluttered. Furthermore, we believe that these method calls are on the same abstraction level which is called to update the model. We assume that the developer who is looking to learn more about the internal workings have sufficient knowledge to read a diagram of this difficulty where an object calls 3-4 methods in sequence which is a relatively simple logic.

This is unlike the “Remove student feature” that included multiple high-level calls (of same abstraction level) as well as lower level method calls from Model to Student.

Furthermore, by abstracting out 3-4 method calls, it could be counterproductive as it would make it less readable from an abrupt cut in the diagram.

Duplicate status (if any):

--