search

kslui99 / pe

0 stars 0 forks source link

Glossary: Single Responsibility Principle unnecessary #15

Open kslui99 opened 2 years ago

kslui99 commented 2 years ago

This principle should not be in your glossary as it is not specific to your project and has a widely-understood definition.

nus-pe-bot commented 2 years ago

Team's Response

The definition is required as it is mentioned in our design goals and some readers might not have knowledge of it.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: Justifying the inclusion of this principle in the glossary with "some readers might not have knowledge of it." opens up a rabbit hole of all sorts of terms in the DG you can define that "readers might not have knowledge of". This is not a strong justification for including a term in the glossary. For example, if we go by the developer team's argument, then the team should also have included a definition for "Use Case", "Non-Functional Requirement", "Logging" etc. and many other terms that "readers might not have knowledge of", making the glossary a dictionary.

As implied by the example in the module textbook, the glossary should include terms used by the developer team that is specific to their project and may be misinterpreted or difficult to understand for readers:

image.png

The developer team clearly took the definition provided by Wikipedia:

image.png

And put it into their glossary:

image.png

Which does not add value to the reader of the Developer Guide.

Different sources also acknowledge pretty much the same definition of Single Responsibility Principle:

image.png

So there is no dispute or misinterpretation about the Single Responsibility Principle to clarify to readers in the first place.

Hence the glossary should not include the definition of Single Responsibility Principle as it is an unnecessary inconvenience for the reader to read this additional piece of information that is widely known in the software engineering industry. Given that the likely readers of the DG are software developers, they will most likely know about this principle already.

Unnecessary terms included in the glossary is considered a bug:

image.png

:question: Issue severity

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

Reason for disagreement: As mentioned in the guidelines, only cosmetic problems should have a very low severity. This bug is not a cosmetic problem.

image.png