Merge pull request #15 from SubnauticaNitrox/guidelines

Updated guidelines with code design principles and updated how-it-works graph

Updated Docusaurus from v2 to v3.5

docs/contributors/contribution-guidelines.md

@@ -6,16 +6,16 @@ sidebar_label: Guidelines
 ### Code Formatting
 Configure your IDE to use the provided `.editorconfig` file. Due to new C# language features, code style can change over time. Remember, consistency is key! If you're unsure, look at the rest of the code.
 
-### Safe guidelines
-When retrieving data from the game, use `Validate.NotNull` or similar where possible. Subnautica is still heavily under development, and things *will* change. Defensive coding standards help identify and fix these changes more easily.
-To reduce redundant if sturctures, there are several helper functions that combine a certain retrieval function with a `Validation` check - it's recommended to use these. For example `GameObject.RequireComponent` and `GuidHelper.RequireObjectFrom`. In case of `Optional<T>` return types, these are unwrapped for you as well, saving the redundant checks *and* unwrapping.
-
 ### Help your fellow developers!
 If code (especially patches that touch game internals) is/are not immediately clear, add a comment explaining the situation. This goes a long way, as you're basically presenting an overview of the research you did in the game code. And it helps others to figure out what's supposed to happen, in case the game changes and the patch is not functioning properly anymore.
 
-### General OO(P) concepts
-... such as "low coupling" and "high coherency", which basically means that you should try to reduce interaction between different pieces of code (classes) as much as possible (low coupling), and make sure that these pieces of code (classes) do the thing they are meant to do, and nothing else (high coherency). This goes a long way in code maintainability; less spaghetti code is always better :wink:
-Also in this case, keep common sense in mind: if you're constantly accessing a lot of fields and methods of another class, consider tucking it away in a method in that class.
+### Basic Code Design principles
+- **<span class="do">DO</span> defensive programming :shield:** <br/>When retrieving data from the game, use `Validate.NotNull`, `Try*` APIs or similar where possible. Log if something unexpected happens. Defensive coding standards help to identify the source of issues before they cause hard to debug problems. This is doubly important for mod projects, as they change the original intent of a code without changing its design. 
+- **<span class="do">DO</span> easy to remove code :wastebasket:** <br/>Removing a type should be trivial. If it causes bugs or significant compile failures, consider refactoring. Try to limit the amount of features a type has and wrap _often accessed code_ into interfaces to reduce coupling to the implementation. 
+- **<span class="do">DO</span> Inversion of Control (IoC) 🔄** <br/>Supply _stateful_ APIs as constructor parameters instead of direct access in methods. Following this practice maintains a chronological order to the written code, i.e. less sphaget :wink:, reducing cognitive load.
+- **<span class="do">DO</span> small interfaces 🔌** <br/>When designing them, think "I need to do X" and generalize for that use, as opposed to "I need to fulfill all needs of X". Split multiple needs into separate interfaces, within reason.
+- **<span class="avoid">AVOID</span> deep type inheritance :seedling:** <br/>If you find yourself needing more than 2 parent types, inheritance is likely the wrong tool to use. Consider compositional- or functional programming.
+- **<span class="avoid">AVOID</span> exact duplicates of code 🗒️** <br />If a piece of code is duplicated in 3 or more places, consider refactoring.
 
 ## Git workflow
 ### Git help
@@ -39,7 +39,7 @@ git config branch.master.pushRemote origin
 
 ### Filing a PR
 When filing a PR, we obviously expect the code to compile, run with no errors, and merge without conflicts.
-To prevent these, and ensure that your code is compatible with the most recent 'version',
+To prevent issues, and ensure that your code is compatible with the most recent 'version',
 merge master into your branch, or rebase your branch on top of master. Even if git(hub) says your code can be merged without conflicts, there might be structural changes (renamings, moved files, refactors, etc), causing the final result to fail compilation, or break at runtime.
 
 It is not desired to remove code just because "it doesn't work", or "causes exceptions in the log". If that's the case, try to fix it (recommended to file the changes in a separate PR), or notify the other Nitrox devs (by creating an issue on github, for example). All code is there for a reason - and someone else spent time creating it.

docs/getting-started/how-it-works.md

@@ -3,4 +3,26 @@ sidebar_position: 1
 title: How it works
 ---
 
-![How it works](https://github.com/SubnauticaNitrox/Documentation/assets/1107063/0088b00a-4580-4f8a-849c-b383cd9e207a)
+```mermaid
+graph TD
+    subgraph server [Server Process]
+        direction LR
+        Server -.-> ServerNitroxModel[NitroxModel]
+        Server --> |calculates world data| Server
+        Server --> |persists world data on save| Storage[(File System)]
+        Storage --> |loads world data on startup| Server
+    end
+    
+    subgraph game [Game Process]
+        direction LR
+        Client --> |adds behaviour with signals| Subnautica --> |signals data| Client
+        Client -.-> ClientNitroxModel[NitroxModel]
+    end
+    server --> |transmits events to all connected clients| game
+    game --> |reports events| server
+```
+
+## Terminology
+
+- **World data** - Data about creatures, vehicles, bases, ...
+- **Signal** - A C#/.NET event or callback

docusaurus.config.js

@@ -1,8 +1,9 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
-const lightCodeTheme = require("prism-react-renderer/themes/github");
-const darkCodeTheme = require("prism-react-renderer/themes/dracula");
+const {themes} = require('prism-react-renderer');
+const lightCodeTheme = themes.github;
+const darkCodeTheme = themes.dracula;
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -33,6 +34,11 @@ const config = {
     locales: ["en"],
   },
 
+  markdown: {
+    mermaid: true,
+  },
+  themes: ['@docusaurus/theme-mermaid'],
+
   presets: [
     [
       "classic",

package.json

@@ -15,16 +15,18 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "2.4.1",
-    "@docusaurus/preset-classic": "2.4.1",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "3.5.2",
+    "@docusaurus/preset-classic": "3.5.2",
+    "@docusaurus/theme-mermaid": "^3.5.2",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^1.2.1",
-    "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "prism-react-renderer": "^2.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.4.1",
+    "@docusaurus/module-type-aliases": "^3.5.2",
+    "@docusaurus/types": "3.5.2",
     "@tsconfig/docusaurus": "^1.0.7",
     "prettier": "3.0.3",
     "typescript": "^4.9.5"
@@ -42,6 +44,6 @@
     ]
   },
   "engines": {
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }