Incomprehensive Developer Guide

[DannyDakota]

No description of add feature.

Incoming developers will not be able to understand how this feature works.

[nus-se-bot]

Team's Response

Not everything has to be included in DG. Furthermore, there is a sequence diagram for Add in DG.

Items for the Tester to Verify

❓ Issue response

Team chose [response.Rejected]

• I disagree

Reason for disagreement: Due to the extreme time constraints of the PE, I wasn't able to provide a comprehensive bug report. Therefore, I would like to highlight that I didn't mean to state "No description" but rather "incomprehensive description" as the title of the bug report suggests. I acknowledge that the team has included a sequence diagram for the add feature. However, the reason I state that "Incoming developers will not be able to understand how this feature works" is that one sequence diagram alone isn't sufficient in explaining how a particular feature is implemented.

The purpose of a technical document as taken from the CS2103T Website is

I don't believe a single sequence diagram alone is able to explain how the add feature is implemented. Furthermore, the team did not include explanations to accompany the inclusion of a sequence diagram.

In addition, the team also lacked other diagrams to give the developer a better understanding of the feature such as activity or class diagrams.

The omission of diagrams such as activity diagrams that are specific to helping the developer understand program behaviour results in the DG being incomprehensive. If the DG were to omit details, then where exactly can a developer go to understand the underlying program behaviour? Activity diagrams allow the developer to understand the underlying workflow when a particular feature is being run. There are multiple actions/branches that can be taken, and different flows to achieve the intended result. The omission of this prevents the developer from understanding the workflows of the feature.

Therefore, I firmly believe that the omission of a proper explanation of the sequence diagram and the lack of usage of other diagrams greatly hinders the reader as he has to refer directly to the code, rendering the developer guide almost useless.

I would also like to revise the severity of this bug to severy.low as i believe that the inclusion of the sequence diagram will allow the developer to achieve some level of understanding, though not significant as they have to ultimately refer to the code to understand the structure of the feature and the different workflows when the feature is executed or incorrectly used. Therefore, it is a minor inconvenience.

---