From 044f4126ed9e8c3712511587f0edc0a592b8915b Mon Sep 17 00:00:00 2001
From: Schmop <lars.richard@rocketmail.com>
Date: Wed, 7 Jun 2023 09:40:07 +0200
Subject: [PATCH] Add notes

---
 .gitignore |   1 +
 Notes.md   | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+)
 create mode 100644 Notes.md

diff --git a/.gitignore b/.gitignore
index 7a1537b..6198bec 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 .idea
 node_modules
+*.html
\ No newline at end of file
diff --git a/Notes.md b/Notes.md
new file mode 100644
index 0000000..2b57aa5
--- /dev/null
+++ b/Notes.md
@@ -0,0 +1,109 @@
+
+
+# Propaganda
+## Transparenz von Schnittstellen
+
+Es fehlt als Konsument die Transparenz, wie Schnittstellen benutzt werden.
+```js
+// @iserv/graph.js
+export function drawGraph(data, options = {}) {
+    [... Implementierungsdetails]
+}
+
+// your-module.js
+/* Wie sieht die API aus? */
+drawGraph([{
+    x: 2,
+    y: 5,
+}, {
+    x: 3,
+    y: 7,
+}]);
+/* Könnte mehrere Formate annehmen */
+drawGraph([
+    5,
+    7
+], {
+    start: 0,
+    stepSize: 1,
+});
+```
+Muss man wirklich immer direkt Dokumentationen oder Implementierungsdetails lesen?
+
+## JSDoc für Schnittstellentransparenz
+```js
+// @iserv/graph.js
+/**
+ * @typedef {Object} GraphOptions
+ * @property {HTMLCanvasElement} mount
+ * @property {number} start
+ * @property {number} stepSize
+ */
+/**
+ * @param {GraphOptions} options
+ */
+export function drawGraph(data, options = {}) {
+    [...Implementierungsdetail]
+}
+// your-module.js
+drawGraph(
+    data, 
+    {
+        mount: document.getElementById('my-canvas'),
+        start: 2,
+        stepSize: 1,
+    },
+)
+```
+## Wobei JSDoc lügen kann:
+```js
+// @iserv/graph.js
+/**
+ * @typedef {Object} GraphOptions
+ * @property {HTMLCanvasElement} mount
+ * @property {number} start
+ * @property {number} stepSize
+ */
+/**
+ * @param {GraphOptions} options
+ */
+export function drawGraph(data, options = {}) {
+    // Erwartet ein Container-Element, kein Canvas!
+    const canvas = document.createElement('canvas');
+    options.mount.appendChild(canvas);
+    // Die Optionen `start` und `stepSize` heißen anders
+    for (let x = options.begin; x < data.length; x += options.step) {
+        [...Implementierungsdetail]
+    }
+}
+```
+
+Wann bekommt man von diesen Fehlern mit?
+
+
+* Bei JSDoc wird nicht automatisch überprüft, ob Schnittstellen eingehalten werden
+* Wenn JSDoc mal valide war, kann es bei Änderungen aber inkonsistent werden
+
+
+# Flüchtigkeitsfehler
+
+## Array access
+```js
+// Rendering required select of users in a group
+const users = fetchUsersInGroup(GROUP_STUDENT_UUID);
+const list = renderList(users);
+const someUser = users[0]; // Just get the first user
+
+// Preselect some user, because the field is required
+list.select(someUser);
+```
+
+Breaks, on empty groups!
+
+```ts
+const users: Users[] = fetchUsersInGroup(GROUP_STUDENT_UUID);
+const list: List<User> = renderList(users);
+// Invalid types, User|undefined vs. User
+const someUser: User = users[0];
+[...]
+```