Incomprehensive Developer Guide

[DannyDakota]

No description of show feature.

As this feature is a feature that the team implemented( not present in AB3), they should definitely include this in the developer guide.

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

[soc-pe-bot]

Team's Response

Not all features has to be included in the developer guide. In particular, the show feature was simple and required minimal lines of code. Due to the straightforward nature of the implementation, it can be assumed that the code itself is clear enough for new developers.

Furthermore, this feature is implemented similarly to the find command in AB3, so the argument that it is "not present in AB3" is invalid.

This also seems more like a suggestion to include the description of the show feature, rather than a bug, and is hence rejected.

Items for the Tester to Verify

❓ Issue response

Team chose [response.Rejected]

• I disagree

Reason for disagreement: I disagree with the reasons the team has provided as they are all based on assumptions.

Firstly, the fact that "not all features has to be included in the DG". I refer to this excerpt taken from the 2103T website:

Screenshot 2022-04-20 at 11.40.57 PM.png

As stated, the document should complement the code and provide enough guidance to get started. However, in this scenario, the document does not complement the code at all as the implementation details are completely omitted from the DG, leaving the developer with only the code to trace through and understand, which is much harder than referring to explanations attached with diagrams.

Secondly, the fact that "feature is implemented similarly to the 'find' command in AB3", therefore making it ok for the team to omit the implementation details in the DG. This argument lies on the assumption that a developer would know immediately that the feature is implemented the same as the find command. How would he know this? This is obviously not the case as the developer would have to painfully trace through the code first before identifying that it is similar to the find command. If the team wanted to complement the code (referring to the screenshot above), they could have stated in the DG that the feature is similar to the find feature in AB3 and provided the link to other relevant documentation. However currently, the developer would have to trace through the code, and there may also be a possibility that he realises that the show command is different as features differ from program to program as the application interacts with different parameters and constraints. With no relevant documentation present, the developer would have to manually understand the program solely based on the code alone.

Also, the team's point about "not present in AB3", from the argument above, I would have to read through the code before identifying this, and that already says a lot about the hindrance brought about to the reader due to team's omission of the underlying implementation of the show feature.

refering to the screenshot above, in fact, the explanation isn't brief when there's no explanation at all.

Therefore, this is a bug as the omission of this feature prevents an incoming developer from understanding what exactly is going on until he reads the code and infringes on the fact that "the documentation should complement the code" as the DG submitted by the team clearly does not. The Developer Guide is thus incomprehensible, lacking the required explanation necessary for new developers and inconveniencing them by having to refer ONLY to the code to understand the underlying implementation.

---

❓ Issue severity

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

• I disagree

Reason for disagreement: Given the time constraints and the frustrations I had as I was struggling to find the relevant documentation for the show feature during the PE, I hastily decided to rate this as severity.High. However, after careful consideration and in response to the team's inputs, I would like to revise this severity to SEVERITY.MEDIUM. This bug causes inconvenience to developers as explained in my reason for disagreement with the rejection. However, the application still remains usable but requires to developer to trace through the code to understand what is going on (where the inconvenience largely arises from).

---