search

delishad21 / pe

0 stars 0 forks source link

Links in developer guide under API leads back to AB3 site #19

Open delishad21 opened 4 months ago

delishad21 commented 4 months ago

The API Hyperlinks do not link to the app's repository. Two examples are here in the Model and Logic sections:

image.png

image.png

This can cause a huge issue for developers that wish to build upon the application but are looking at the wrong APIs and implement the wrong items.

soc-pe-bot commented 4 months ago

Team's Response

This is an issue, but it is not medium severity. It should not affect users very often.

Items for the Tester to Verify

:question: Issue severity

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

Reason for disagreement: This issue may not affect users often, but it will definitely affect developers, who are the likely audience of this developer guide.

Based on the course textbook, the API

specifies the interface through which other programs can interact with a software component.

Any developer that is basing their developments on the API that you have linked (AB3's API) would be facing severe consequences as they would be developing using an outdated interface.

For example: the team's Model API has been updated from AB3, now including a few more methods, including the undo and redo methods. Say a developer would like to build upon the undo/redo feature, or would like to create a command that makes use of the undo/redo functionalities. Should he base his implementation off the AB3 API that the team has linked, he would incorrectly assume that the Model component does not have behavior for dealing with the undo/redo feature, which would prompt him to search elsewhere or to implement methods himself to achieve the same functionality. This leads to potential code duplication and can result in confusion for developers.

The incorrect linking of the API also causes inconsistencies in the guide. Under the implementation section for the Undo/Redo feature, it is shown in the diagram that the Model object has a undoAddressBook() method.

image.png

However, this method is not in the linked API. To further complicate matters, there is an earlier typo at the start of the section which states that the section is a "Proposed Implemention" for Undo/Redo. This can lead to even more confusion and misunderstanding as developers struggle to figure out the correct API for Model and if the proposed implementation was actually the implementation that the developer team used to implement their undo/redo feature.

The confusion, misunderstanding and inconvenience that this issue can cause to developers makes this issue deserving of a severity.Medium label