mirror of
https://github.com/RPG-Research/bcirpg.git
synced 2024-04-16 14:23:01 +00:00
Updated UML Guidelines (markdown)
RPG Research
parent
6c181b91b6
commit
4664402a46
@ -1,72 +1,80 @@
|
||||
UML Guidelines
|
||||
# UML Guidelines
|
||||
|
||||
General Flowcharts and Unified Modeling Language (UML) is used as part of the design phase of all our projects.
|
||||
|
||||
This page is to help define any "House Rules" we have decided upon with our implementation of UML visual design documentation.
|
||||
UML is a very flexible language, and as such there are not always hard and fast rules about which symbols are used in which way consistently. Each organization over time ends with their own "dialect" of UML implementation UI.
|
||||
|
||||
In role-playing game terms think of it this way.
|
||||
The UML specifications are the "Rules As Written" (RAW) of the role-playing game core systems book. Over time various supplement rules are published, that may be added as additional RAW or excluded as "not core rules". In some cases the added rules might conflict with the core rules, requiring each group to decide which of the rules they want to follow and which t exclude.
|
||||
Additionally, during game play, situations come up that are not clearly defined in the core or supplementary rules, so the Game Master (and group) need to figure out a way to resolve the situation. These decisions in the group are generally known as "House Rules" in the TRPG world.
|
||||
## RPG Analogy
|
||||
|
||||
In role-playing game terms think of it this way:
|
||||
The UML specifications are the "Rules As Written" (RAW) of the role-playing game core systems book. Over time various supplement rules are published, that may be added as additional RAW or excluded as "not core rules". In some cases the added rules might conflict with the core rules, requiring each group to decide which of the rules they want to follow and which to exclude.
|
||||
|
||||
Additionally, during game play, situations occur that are not clearly defined in the core or supplementary rules, so the Game Master (and group) need to figure out a way to resolve the situation. These decisions in the group are generally known as "House Rules" in the TRPG world.
|
||||
|
||||
This section of the Wiki is to track these UML "House Rules" decisions as we make them, so that all designers and developers are on the same page, and can keep up to date if changes occur.
|
||||
|
||||
# Why Design-First Instead of Code-First?
|
||||
|
||||
While it has become (arguably erroneously) popular since about 2010-2015+ to regress back to code-first, design-later, this invariably leads to unscalable and unsustainable projects. The code-first approach works okay for small, non-distributed projects, the "quick and dirty" code. But for more complex projects, the code-first approach invariably leads to chaos the moment you try to distribute the work across other developers. The code-first approach gives the illusion of more progress sooner, and does in the short term, but in the long run begins to bog down horribly, leadin to (at best) only being able to release code for 10% of the time toward new features and improvements code (forward progression of the code base features and scaling), 85% debugging/fixing (trying to maintain/fix the existing code base), <5% documentation. This all leads to an overall garbage codebase that can't be scaled, or maintained, especially when constantly changing developer eyeballs/brains. Typically unable to move beyond 3.x iterations without major overhauls.
|
||||
|
||||
The design-first approach, if correctly implemented with Object Oriented principles, typically leads to much more sustainable and distributable codebase over time. This usually means it works out to time spent around: 10-20% on documentation, 20-50% toward new features coding iteration (forward progression of the code base), 20-40% debugging/iteration (trying to maintain/fix the existing code base), and is SO much easier to collaborate, maintain, and support over many years and many different eyeballs and brains.
|
||||
|
||||
## OO Principles
|
||||
|
||||
We follow the principles of Object Oriented Design (OOD), even when not using OO languages. The design-first approach means does mean that it takes a little longer (at first) before we are actually write working code (in the early phases), but overall it leads to an exponentially more sustainable, scalable, distributable, flexible, and manageable product overall, able to iteration past 10.x revisions and beyond, without complete overhaul, especially if Design Patterns and Refactoring becomes part of the regular process.
|
||||
|
||||
Once a UML class diagram and the other documentation are in place, it is easy to have someone volunteer to take on creating the code for that class/feature in a much more consistent way. And if they don't finish, or get stuck, make it much easier for others to come in and help.
|
||||
|
||||
|
||||
## Visual Design Aides: Flowcharts and UML
|
||||
|
||||
We also use UML as a visual aide to help with the design documentation. UML is flexible in specific implementation, with many variations of the visual representations in degree and detail, and that is a boon of UML.
|
||||
|
||||
This document attempts to establish within this development community the visual design standards we want to follow with our diagrams, so we're all on the same page when looking at the code.
|
||||
# Purpose of This Page
|
||||
|
||||
Once a UML class diagram and the other documentation are in place, it is easy to have someone volunteer to take on creating the code for that class/feature in a much more consistent way. And if they don't finish, or get stuck, make it much easier for others to come in and help.
|
||||
This document attempts to establish within this development community the visual design standards we want to follow with our diagrams, so we're all on the same page when looking at the code. We don't need to track all UML rules, just the "House Rules" decisions that this community makes over time.
|
||||
|
||||
# Documentation Required to Contribute to This Project
|
||||
|
||||
If you wish to contribute coding to this project, then we ask you to please make yourself at least somewhat familiar with these OO and UML principles.
|
||||
|
||||
We REQUIRE you to document your code proposals BEFORE you submit actual code. At the bare minimum we want to see:
|
||||
Narrative User Use Case explaining what you want a feature to do from the user perspective.
|
||||
Narrative Developer Use Case explaining the "under the hood" goals of your code, what you expect it to do, how you expect it to do it, etc.
|
||||
A general workflow diagram to go with each narrative.
|
||||
A UML class diagram to accompany the code proposal.
|
||||
* Narrative User Use Case explaining what you want a feature to do from the user perspective.
|
||||
* Narrative Developer Use Case explaining the "under the hood" goals of your code, what you expect it to do, how you expect it to do it, etc.
|
||||
* A general workflow diagram to go with each narrative.
|
||||
* A UML class diagram to accompany the code proposal.
|
||||
|
||||
You are of course welcome to write your code, trying to figure this out, but before you try submitting it to our branch, you MUST PROVIDE THIS DOCUMENTATION BEFORE WE CAN ACCEPT IT.
|
||||
|
||||
Here are some recommended resources:
|
||||
|
||||
Online:
|
||||
|
||||
Introduction to concepts:
|
||||
https://medium.com/nerd-for-tech/principles-of-object-oriented-design-556edf6987be
|
||||
https://www.oodesign.com/design-principles
|
||||
https://www.educative.io/courses/grokking-the-low-level-design-interview-using-ood-principles
|
||||
https://www.educba.com/class-diagram/
|
||||
https://blogs.sap.com/2022/05/27/abap-oo-design-7-basic-oo-principles-summary/
|
||||
|
||||
Design guides:
|
||||
https://www.visual-paradigm.com/guide/uml-unified-modeling-language/uml-class-diagram-tutorial/
|
||||
https://creately.com/blog/software-teams/class-diagram-tutorial/
|
||||
## Online:
|
||||
* **Introduction to concepts:**
|
||||
> * https://medium.com/nerd-for-tech/principles-of-object-oriented-design-556edf6987be
|
||||
> * https://www.oodesign.com/design-principles
|
||||
> * https://www.educative.io/courses/grokking-the-low-level-design-interview-using-ood-principles
|
||||
> * https://www.educba.com/class-diagram/
|
||||
> * https://blogs.sap.com/2022/05/27/abap-oo-design-7-basic-oo-principles-summary/
|
||||
* **Design guides:**
|
||||
> * https://www.visual-paradigm.com/guide/uml-unified-modeling-language/uml-class-diagram-tutorial/
|
||||
> * https://creately.com/blog/software-teams/class-diagram-tutorial/
|
||||
|
||||
|
||||
|
||||
Books:
|
||||
|
||||
Required:
|
||||
Godot Engine Game Development
|
||||
UML Distilled 3rd Edition
|
||||
Design Patterns - Coding
|
||||
|
||||
Recommended:
|
||||
Learning UML 2.0 - O’Reilly
|
||||
|
||||
|
||||
|
||||
Also Helpful:
|
||||
Universal Principles of Design (Lidwell) - UI/UX
|
||||
Game Programming Patterns - Game Design
|
||||
UML Modelling Language
|
||||
|
||||
|
||||
UML For Mere Mortals
|
||||
UML for Dummies
|
||||
## Books:
|
||||
* **Required:**
|
||||
> * Godot Engine Game Development
|
||||
> * UML Distilled 3rd Edition
|
||||
> * Design Patterns - Coding
|
||||
* **Recommended:**
|
||||
> * Learning UML 2.0 - O’Reilly
|
||||
* **Also Helpful:**
|
||||
> * Universal Principles of Design (Lidwell) - UI/UX
|
||||
> * Game Programming Patterns - Game Design
|
||||
> * UML Modelling Language
|
||||
> * UML For Mere Mortals
|
||||
> * UML for Dummies
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user