Developer guide: Class diagram static variables

[damiwee]

(static) class level variables should be underlined. By not showing that it's class level, readers may be misled.

dg:

from github:

[nus-se-bot]

Team's Response

This is a minor typo affecting the information given in a sequence diagram, hence the downgrade from High to Low.

Items for the Tester to Verify

:question: Issue severity

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

• [x] I disagree

Reason for disagreement: This is not just a cosmetic issue. Labeling the absence of underlining for static variables and methods in the UML class diagram as "high" severity isn't solely due to the mistake itself, but rather due to its nature being an inaccurate documentation bug and its potential to subtly influence other developers' design considerations without direct awareness of the error. Although abstraction is accepted as a means of simplification, discrepancies or inconsistencies in comparison to the actual code such as this bug cannot be accepted as they can result in confusion, misinterpretation, and ultimately, incorrect assumptions about the system's behavior and functionality.

This nature of the mistake can impact developer design practices, jeopardizing the integrity of the codebase by misaligning with design intentions, risking inconsistent design patterns, and compromising modularity and encapsulation crucial for maintainable code.

Such a flaw not only hampers code understandability and maintainability but also increases the risk of errors and inefficiencies in development efforts. Addressing this issue promptly is important for upholding the quality and coherence of the software architecture and ensuring the long-term viability of the product.

Additionally, envision a scenario where a team of developers, misled by the absence of underlining (or any inaccurate documentation that wrongly describes the code), invests significant time and effort in writing code based on an erroneous understanding of the system's static elements (or any other subsystem). Later, upon realizing the standard convention, they discover a more efficient and elegant design approach already exists, rendering their previous efforts redundant and resulting in wasted time, money, and resources, underscoring the importance of rectifying such design inconsistencies to avoid costly rework and maximize development efficiency.

However, now in hindsight and with reference to the course material, I would argue to change the label to be medium severity as inaccurate design documentation that claims one thing but in fact is not, no matter how minor, can cause miscommunication and can have severe implications via the ripple effect if not caught early. However, for this particular documentation bug, perhaps 'high' severity label is too harsh, and hence as mentioned, I would like to reduce it to medium.

---