search

nus-cs2113-AY2324S2 / pe-dev-response

0 stars 0 forks source link

Missing diagrams for Record component #2475

Open nus-se-script opened 2 months ago

nus-se-script commented 2 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.

Missing sequence diagram and class diagram.

Explanation is way too long and can be simplified with the help of diagrams.

image.png

[original: nus-cs2113-AY2324S2/pe-interim#2410] [original labels: severity.Medium type.DocumentationBug]

Geinzit commented 2 months ago

Team's Response

The class and sequence diagram is shown at the top of 'Design / Implementation' section of the DG. It's not missing. An argument can be made that each component should get separate diagrams for easy viewing, but that's not in the scope of this issue.

We don't consider the explanations to be way too long, because some members of the Record component like the problem set ID, problem set type etc. Can be confusing to software engineers in terms of its logic and purpose. The Record component especially so in this regard which is why this section gives more explanations on the justification and the details of its implementation that simply cannot be conveyed through a class or sequence diagram. Examples are "why are there two separate constructors", "why does the print method outputs different formats when the speed is 0", "In what format is each record saved to external files so I can safely edit them for testing without breaking it" etc. These are questions that developers would like to have answered and these sections, albeit lengthy, does just that.

Duplicate status (if any):

--