Incomprehensive developer guide

[DannyDakota]

No description of sort feature.

As this feature is a feature that the team implemented, they should definitely include this in the DG

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

[soc-se-bot]

Team's Response

This is definitely not a issue with high severity, according to the scheme given:

This is due to the following reasons:

1. Not all features implemented by a team should be included in the DG. This would cause the DG to be too lengthy, instead of focusing on controversial implementations and hard to implement features.
2. Sorting is highly common in software applications, which means there are many resources documenting the behaviour (e.g. this oracle docs which is very concise).
3. The sorting feature is highly similar to filtering the ObservableList, which helps provide insights to new developers on how the command works.

Furthermore, this seems like a suggestion to include an explanation of the sort feature, which we explained above as being unnecessary, rather than a bug in our DG, hence rejected.

Items for the Tester to Verify

❓ Issue response

Team chose [response.Rejected]

• I disagree

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

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

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 "sorting is highly common and thus there are many resources out there that document its behaviour", 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 sorting method used would be the same as the sorting methods used in other applications. 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 might be similar to other sorting programs. If the team wanted to complement the code (referring to the screenshot above), they could have stated in the DG that the sorting program used is similar to many other applications 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 sorting behaviour is different as sorting behaviour differs 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. Furthermore, the link provided by the team refers only to the Java class documentation on SortedList, which bears no significance on the application used by the team as the underlying implementation (e.g how the objects interact with each other, what the structure of the sort feature is and the execution path of a sort command) is completely omitted.

The third point is similar to the second point. How would a new developer for the application know that the sorting feature is similar to filtering the ObservableList when no mention of this is stated in the Developer Guide. He can only do this only through tracing through the code and this is highly inconvenient.

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 sorting 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).

---