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 = renderList(users); +// Invalid types, User|undefined vs. User +const someUser: User = users[0]; +[...] +```