nus-pe-bot
commented
2 years ago Team's Response
Hi,
We chose to omit these details to avoid cluttering of the UML diagrams. The intent of our UML diagram is to show the general flow of the command. Should there require any further clarification, we feel that it is fair to expect the developer to dive deeper into the code to understand the code, and hence unnecessary for the DG to include such details. As such we don't believe this to be a bug.
We also feel that the severity of this issue should be low as this does not impede the understanding of the reader as it still carries the information a UML diagram should.
Best Regards!
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: I disagree with the rejection of this report, as this lack of explanations in the DG can indeed serve to hinder the reader's understanding.
When a developer reads the 'Implementation' section of a Developer Guide, they do so with the intent of understanding the specific implementation of various features, so that they can understand how to work with the said feature, or with similar features. If they wanted to understand the 'general flow' of how commands work, information on the 'general flow' of commands is already covered in the explanation of the Logic Section found earlier in the guide, as shown below.
Therefore, the current UML diagrams in the 'Implementation' section, as they are now, add no value whatsoever to the developer's understanding of the feature. To use the Tab feature implementation section as an example to illustrate this point, the UML diagram is practically identical to that of the delete command example, shown below, given in the earlier section explaining the Logic component of the program, the section in which the 'general flow' of commands is already explained.
Context-specific information, such as how each step of the Command execution works in this context, how the Logic component interacts with the Model, and how that interacts with the UI component through the setCurrentTab(t) method, and other specific details are probably what a developer reading this section is looking for, but they are not given.
The text preceding the diagram for the Tab feature simply describes the feature itself, something that can also be found in the User Guide. Thus, this section does not provide any additional useful information to a developer regarding the implementation of the Tab feature whatsoever, and any developer hoping to find such information in this section would gain no new knowledge.
The UML Sequence diagrams for the implementation of the Tabs feature and Find feature do not have relevant explanations regarding the steps and methods involved, and thus appear to be irrelevant to the text around them. This may hinder the reader's ability to understand the implementation of these features, especially if they are unfamiliar with the class and method names.
Would recommend adding a label to each diagram as well as a section of text under each implementation, explaining what each class and method shown in the diagrams are and what they do.