search

jensonjenkins / pe

0 stars 0 forks source link

Incorrect sequence diagram notation #9

Open jensonjenkins opened 2 months ago

jensonjenkins commented 2 months ago

Throughout the DG, there are multiple sequence diagrams where the leftmost entity is seen to be :User where the existence of a User class is nowhere to be found. If the intention was to have the :User entity represent an actual user, then an actual user entity (refer to the last attached image) would have been more clear to future developers reading the documentation.

Examples are attached below: image.png

image.png

image.png

CS2113 Website Example:

image.png

nus-se-bot commented 2 months ago

Team's Response

Thank you for pointing this out. However as this is merely a cosmetic issue in the DG, we feel that the severity should be very low.

Items for the Tester to Verify

:question: Issue severity

Team chose [severity.VeryLow] Originally [severity.Medium]

Reason for disagreement: Thank you for acknowledging the problem, however I'm afraid I have to disagree with the fact that this is "merely a cosmetic issue". Cosmetic issues by definition refer to typos/spacing/layout/colour/font issues, this however, is an issue with notation and how readers may be able to misinterpret the sequence diagram.

Keep in mind the problem here is not only that you need an icon to differentiate the actor and components, but its that you are drawing all (7/7) sequence diagrams as if a User class exists (indicated by the :User block) and interacts with other classes when it does not. This may mislead DG readers to believing that there exists a User class in the program and interacts with other classes. So by that reasoning, ruling it as severity.VeryLow is already incorrect as it is not a mere cosmetic issue.

The argument that the ":" is a simple typo is questionable as the typo consistently occurs in all diagrams and results in a very different interpretation of the diagram. Furthermore, the notation adopted by this course is shown below where an actor is explicitly represented (not as a block).

image.png

It could have been a severity.Low had this only happen once or twice in the DG. Unfortunately this issue persists in all 7 sequence diagrams. At that level of consistency, it is highly likely for readers to misinterpret the sequence diagrams into believing that a User class exists without looking at the actual code. Hence my reason for choosing severity.Medium.