search

tituschewxj / pe

0 stars 0 forks source link

Wrong syntax for labels in UML class diagrams #8

Open tituschewxj opened 2 months ago

tituschewxj commented 2 months ago

Current Behaviour

This class diagram uses <<create>>, <<use>> for it's labels.

image.png

Expected Behaviour

According to this, labels should be of the form creates >.

As it is not mentioned that an alternative syntax is used in the developer guide, I put this as a documentation bug.

nus-se-bot commented 2 months ago

Team's Response

Thank you for your feedback.

We referenced the AB3 diagram which utilizes the same exact notations that you have mentioned, which is <<create>> and <<use>> labels. You may find the diagram here https://se-education.org/addressbook-level3/DeveloperGuide.html under the Parser Diagram.

We also wish to also note the issue that you have raised is for an Architecture Diagram - while the URL reference that you have kindly provided is for a Class diagram.

We appreciate your feedback on the matter.

Have a Nice day.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: The response should be response.Accepted, as it could be improved to follow the structure given in the notes. Correcting this mistake only requires a small change (mentioned below), so it doesn't qualify for not in scope.

I believe this is still severity.VeryLow as it does not hurt the diagram much, but non-standard notation was used, without explanation of the syntax to the reader.

We also wish to also note the issue that you have raised is for an Architecture Diagram

I disagree that it is an architecture diagram, as architecture diagrams are meant to provide a high level view of a system, while a class diagrams are meant to show the structure of a system, focusing on the classes and their relationships.

In the Developer Guide, it is stated that diagrams of this form are (partial) class diagrams, and not architecture diagrams. It is reasonable to assume that the diagram shown in the bug report is also a (partial) class diagram, otherwise the diagrams would be inconsistent.

image.png

PlantUML allows using the arrow notation in the label, so this is something that could be improved, and is not an issue with the diagramming tool.

image.png

We referenced the AB3 diagram which utilizes the same exact notations that you have mentioned, which is <> and <> labels. You may find the diagram here https://se-education.org/addressbook-level3/DeveloperGuide.html under the Parser Diagram.

Quoting the PE3 page:

image.png

Additionally, I believe the current choice of syntax for the label is not as good as the one in the notes, as including the arrow head notation in the label adds some value to the diagram, as it indicates the direction in which the label is read, so is something that could be included.

image.png

Due to the inconsistencies between the standard UML notation taught, I believe this is still an improvement the current developer guide could make.