diff --git a/website/assignments/git-Doku-CleanCode.md b/website/assignments/git-Doku-CleanCode.md new file mode 100644 index 0000000000000000000000000000000000000000..cb14fd257c0a14f144de65d6b981b0774a3e3985 --- /dev/null +++ b/website/assignments/git-Doku-CleanCode.md @@ -0,0 +1,29 @@ +# Ãœbungen Software-Entwicklung 3: `git`, Dokumentation, Clean Code + +## Ausgangslage +In der Vorlesung haben Sie weitergehende Konzepte zu `git`, Dokumentation und Clean Code kennengelernt. Diese sollen nun auf Ihr Projekt angewandt werden. + +## Aufgabe +* Ãœberlegen Sie sich im Team, wie Sie mit `git` umgehen möchten. + * Wie sieht Ihr Workflow aus? + * Wie möchten Sie mit Branches umgehen? + * Wann werden Tags erstellt? Wie ist Ihre Versionsschematik? +* Erstellen Sie in Ihrem Repository ein Changelog, in dem Ihre Änderungen festhalten und pflegen. +* Erstellen Sie eine Readme, die beschreibt, wie Ihr Projekt gestartet wird. +* Legen Sie Ihre Projektdokumentation in einem Wiki ab. +* Prüfen Sie Ihren vorhandenen Code auf die `SOLID`-Prinzipien und passen diesen ggf. entsprechend an. + * Sind Benennungen so gewählt, dass diese keine weitere Erklärung benötigen? + * Sind Ihre Klassen immer gleichartig strukturiert? + +## Tipps +* Nutzen Sie `git` auf der Commandline. Das hilft, die Konzepte zu verinnerlichen. +* Scheuen Sie sich nicht vor `merge`-Konflikten! Nach ein paar Mal, ist es nicht mehr so schlimm 😊 +* Nutzen Sie `merge`-Requests, um sich gegenseitig zu reviewen. +* Schauen Sie in das [Vorlesungsprojekt](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt). Hier finden Sie eine Möglichkeit wie Sie Beispiele wie die `SOLID`-Prinzipien umgesetzt werden können. + +## Ziele +* Sie können mit `git` umgehen und haben eine Vorgehensweise für branches definiert. +* Changelogs dokumentieren wesentliche Änderungen Ihres Projekts. +* Eine Readme beschreibt wie Ihr Projekt gestartet werden kann. +* Ihre Dokumentation liegt in einem Wiki ab. +* Die `SOLID`-Prinzipen werden in Ihrem Projekt angewandt. \ No newline at end of file diff --git a/website/clean-code_doku_git.html b/website/clean-code_doku_git.html new file mode 100644 index 0000000000000000000000000000000000000000..a74473d645fcc546c725125cfa9d505cd332a4a6 --- /dev/null +++ b/website/clean-code_doku_git.html @@ -0,0 +1,311 @@ +<!DOCTYPE html> +<html> + <head> + <title>Softwarearchitektur</title> + <meta charset="utf-8"> + <link href="css/hdm.css" rel="stylesheet"></link> + <style> + @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz); + @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic); + @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic); + + body { font-family: 'Droid Serif'; } + h1, h2, h3 { + font-family: 'Yanone Kaffeesatz'; + font-weight: normal; + } + .remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; } + </style> + </head> + <body> + <textarea id="source"> + +class: center, middle, first + +# Software-Entwicklung 3 + +## git, Dokumentation, Clean Code + +--- + +# Agenda + +1. Recap +2. Arbeit mit git +3. Dokumentation +4. Clean Code + + +--- + +# Recap: Was haben wir letzte Woche besprochen? + +* Softwarearchitektur +* Basisprinzipien der Softwarearchitektur +* Praktisches Beispiel + +> Blick ins [Repository](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt) + +--- + +# Arbeit mit VCS + +VCS = **V**ersion **C**ontrol **S**ystem + +Ablage von Dateien/Ordnern, die nicht aus anderen versionierten Dateien abgeleitet werden können. Beispielsweise sollten `.class`-Dateien nicht in einem VCS verwaltet werden. + +Heute Fokus auf Teamarbeit mit `git` + +--- + +# `git` Basisbefehle + +* `git pull REMOTE TARGET-BRANCH`: Updates aus Remote-Repo laden und in TARGET-BRANCH mergen +* `git status`: Status des Repo. Zeigt z.B., ob Dateien noch nicht commited wurden +* `git log`: Zeigt die History des aktuellen Branches an + +Erklärungen zu sämtlichen Befehlen: [git Cheat Sheet](https://training.github.com/downloads/de/github-git-cheat-sheet/) + +--- +# `git graph` + +Anzeige der commits und branches als Graph. + +**git CLI** +```bash +git log --all --decorate --oneline --graph + +# Beenden mit ":q" +``` + +**GitLab** + +_Repo-Seite_ âž¡ï¸ **Repository** âž¡ï¸ **Graph** + +Beispiel: https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt/-/network/main + +--- +# Erstellen eines Branches und Merge + +```bash +git branch my-new-branch + +git checkout my-new-branch # Abkürzung: git checkout -b my-new-branch + +# Änderungen machen + +git add --all + +git commit -m "update README.md" + +git checkout main + +git merge my-new-branch + +``` +--- +# Merge conflicts beheben + +Entstehen, wenn in beiden Branches (source und target) in der gleichen Zeile Änderungen vorgenommen wurden. + +```bash +git checkout <TARGET BRANCH> + +git merge <SOURCE BRANCH> + +# Konflikt mit Editor beheben. Entscheiden, welche Änderung "korrekt" ist. + +git add <AFFECTED FILES> + +git commit -m "merged TARGET BRANCH" + +# Ergänzung: Merge abbrechen +git merge --abort +``` + +--- +# git flow +* Besteht aus + * mehreren Feature Branches, d.h. parallele Entwicklungsstränge + * langlebige Branches + * Integrationstests auf `develop` + * Releases auf `main`, inkl. Tags +* Merge auf `main` wird oft nur von bestimmten Personen durchgeführt +* Geeignet z.B. für feste Releasezyklen +* git flow Cheatsheet: http://danielkummer.github.io/git-flow-cheatsheet/ + +<img src="img/git-doku-cleancode/git-flow.png" alt="git flow" width="60%"/> + +--- +# Trunk-basierte Entwicklung mit git + +* Geeignet, **häufige** und **kleine Änderungen** in einem Hauptbranch (_Trunk_, oft `main`) einfließen sollen. +* Alle haben Zugriff auf alle Branches, auch `main` +* Grundannahme: Trunk-Branch ist immer stabil und bereit für Deployment. +* Kleine Branches. Dadurch weniger Konflikte beim merge. + +<img src="img/git-doku-cleancode/git-tdd.png" alt="Trunk based development" width="90%"/> + +--- +# `merge` requests in GitLab + +* Kann Bestandteil eines Reviewprozesses sein + +> [Demo im Repo](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt) + +--- +# `cherry pick` + +* Kopieren einzelner Änderungen/Commits von einem Branch in einen anderen. +* Sinnvoll, wenn an zwei Branches gearbeitet wird und eine Änderung vor dem `merge` benötigt wird. Beispiel: Hotfix. + +## Schritte +1. Commit ID herausfinden, die kopiert werden soll: `git log` +2. Wechseln in den Branch, in dem der Commit kopiert werden soll: `git checkout BRANCHNAME` +3. Kopieren des Commits in den aktuellen Branch (mit neuem Commit): `git cherry-pick COMMIT-ID [COMMIT-ID COMMIT-ID]` +4. _Kopieren des Commits in den aktuellen Branch (ohne neuem Commit): `git cherry-pick COMMIT-ID [COMMIT-ID COMMIT-ID] -n`_ + +--- +# git Tricks + +* `.gitignore`: Datei, in der angegeben werden kann, welche Dateien/Ordner nicht versioniert werden sollen + +> [Sammlung mit `.gitignore`-Konfigurationen](https://github.com/github/gitignore) + +--- +# Tagging und Semantic Versioning + +* [Semantic Versioning](https://semver.org): Dreiteilige Versionsnummern. Z.B. `v2.3.1`. +* Muster `v{Major}.{Minor}.{Patch}` + * `Major`: (API-)Änderungen, die nicht mehr kompatibel zu Vorgängerversionen sind. + * `Minor`: (API-)Änderungen, die kompatibel zu Vorgängerversionen sind. + * `Patch`: Bug-Behebungen, keine API-Änderungen. + +## Tagging mit git + +* Tag = Versionsnummer, die auf einen commit zeigt + +```bash +git tag -a TAGNAME COMMIT-ID +``` + +* Alternativ mit GitLab + +--- +# Changelogs + +* Dokumentieren, was eine spezifische Version auszeichnet. + * Was ist neu? + * Was wurde geändert? + * Welche Funktionen werden in Zukunft entfernt? + * Welche Funktionen wurden entfernt? + * Welche Bugs wurden behoben? + * Welche Security-Probleme wurden behoben? +* Weitere Infos: [Keep a changelog](https://keepachangelog.com/de/1.0.0/) + +--- + +# Tricks in GitLab + + `git commit -m "Arbeit an Issue #2"` + +Verknüpft Commits mit Issues. Sinnvoll für Nachvollziehbarkeit. + +--- +class: center, middle +# Dokumentation & Issue Management + + +--- +# Dokumentationsformen + +* Doku am Code (`javadoc`), sofern notwendig +* Doku im Repository + * Readme, z.B. mit Anleitung wie das Programm gestartet werden kann + * Changelog +* Technische Dokumentation +* Enduser Doku + +> Schulungen mitdenken! + +--- +# Nutzen eines Wikis + +> [Demo im Repo](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt) + +# Nutzen von Milestones + +> [Demo im Repo](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt) +--- +class: center, middle +# Clean code + +--- +# Warum ist clean code wichtig? + +* Ursprung: Buch "Clean Code", Robert C. Martin, Sammlung von Prinzipien um clean code zu erreichen +* Ziele: + * Code leichter verständlich machen + * Wartbarkeit des Codes erhöhen + * Einheitlichkeit schaffen + * Projektorganisation + * (Selbst-)Organisation + +--- +# SOLID Prinzipien + +_Teilweise Wiederholung_ + +* **S**ingle Responsibilty Principle: + * Jede Klasse sollte nur eine Aufgabe bearbeiten, Speichern in Model-Klasse auslagern +* **O**pen Closed Princple: + * Offen für Erweiterung, geschlossen für Veränderung + * Info-Methode für Audio/Videos auslagern +* **L**iskov'sches Substiotions Prinzip: + * Unterklassen erweitern Oberklassen + * Unterklassen dürfen Verhalten der Oberklassen nicht einschränken +* **I**nterface Segregation Principle: + * Große Schnittstellen in kleinere, modularere Schnittstellen aufteilen +* **D**ependency Inversion Principle: + * Interfaces statt konkreter Implementierung + * Gruppierende Methoden + +> Demo + +--- +# Umgang mit Benennungen +* Es soll kein Kommentar für Variablenbenennungen notwendig sein +* Variablendefinition an dem Ort, wo sie definiert werden +* Nicht zu viele Kommentare, Code sollte ohne verständlich sein + + +--- +# Eindeutigkeit + +* Gleichartige Struktur: Z.B. Wie sind Klassen strutkturiert + * Wo befinden sich `imports`, Konstruktoren, Methoden etc.? + * Unterstützung durch IDE, i.S.v. Templates + * Kann automatisiert über statische Codeanalyse/Lint (z.B. [SonarCube](https://docs.sonarqube.org/latest/)) geprüft werden +* Jede Methode sollte nur eine Sache tun, ggf. aufteilen in mehrere Methoden + +--- +# Zusammenfassung der Clean Code Regeln + +> [Tutorials zu Clean Code, TU Dortmund](https://sopra.cs.tu-dortmund.de/wiki/_media/infos/tutorials/cleancode/cleancode_paper.pdf) + + +> [Clean Code Tugenden, clean-code-developer.de](https://clean-code-developer.de/die-tugenden/) + +**Nicht immer sind alle Clean Code praktikabel!** + +--- +# Refactoring des Demoprojekts + + </textarea> + <script src="https://remarkjs.com/downloads/remark-latest.min.js"> + </script> + <script> + var slideshow = remark.create(); + </script> + </body> +</html> \ No newline at end of file diff --git a/website/img/.DS_Store b/website/img/.DS_Store index c8257567d38aa320195d96648b799515089356d8..f493a5139ba44fb88a05dbb372e5aef51ea73c18 100644 Binary files a/website/img/.DS_Store and b/website/img/.DS_Store differ diff --git a/website/img/git-doku-cleancode/git-flow.png b/website/img/git-doku-cleancode/git-flow.png new file mode 100644 index 0000000000000000000000000000000000000000..ab9ac617451a5ed32550c853b170d7760bb264cb Binary files /dev/null and b/website/img/git-doku-cleancode/git-flow.png differ diff --git a/website/img/git-doku-cleancode/git-tdd.png b/website/img/git-doku-cleancode/git-tdd.png new file mode 100644 index 0000000000000000000000000000000000000000..8bff943cb8d3b8f9fb7ca3bf2587b0bafe8ce25e Binary files /dev/null and b/website/img/git-doku-cleancode/git-tdd.png differ diff --git a/website/index.html b/website/index.html index e4c8cee4fa930d154148822c809751cdc0cf2efe..b7a81f909272cf5f1cc12124f098970bd9b3549a 100644 --- a/website/index.html +++ b/website/index.html @@ -13,12 +13,14 @@ <li><a href="einfuehrung.html" target="_blank">Einführung</a></li> <li><a href="anforderungsanalyse.html" target="_blank">Anforderungsanalyse</a></li> <li><a href="softwarearchitektur.html" target="_blank">Softwarearchitektur</a></li> + <li><a href="clean-code_doku_git.html" target="_blank">git, Dokumentation, Clean Code</a></li> </ul> <h3>Vorlesungnotizen</h3> <ul> <li><a href="https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022vorlesung/-/blob/main/website/lecturenotes/20220321.md" target="_blank">Vorlesungsnotizen - 21.03.2022</a></li> <li><a href="https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022vorlesung/-/blob/main/website/lecturenotes/20220328.md" target="_blank">Vorlesungsnotizen - 28.03.2022</a></li> + <li><a href="https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022vorlesung/-/blob/main/website/lecturenotes/20220404.md" target="_blank">Vorlesungsnotizen - 04.04.2022</a></li> </ul> <h3>Projekt</h3> @@ -34,6 +36,7 @@ <ul> <li><a href="https://e-learning.hdm-stuttgart.de/moodle/course/view.php?id=3828" target="_blank">Moodle-Kurs</a> </li> <li><a href="https://konferenz1.hdm-stuttgart.de/b/jor-hzf-odu-rxi" target="_blank">BBB zur Vorlesung</a> </li> + <li><a href="https://konferenz1.hdm-stuttgart.de/b/jor-r4x-ias-ytk" target="_blank">BBB zu den Ãœbungen</a> </li> <li><a href="https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022vorlesung" target="_blank">GitLab: Vorlesungsdemos</a> </li> <li><a href="https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2022projekt" target="_blank">GitLab: Vorlesungsprojekt</a> </li> </ul> diff --git a/website/lecturenotes/20220328.md b/website/lecturenotes/20220328.md index 5d985d5e1690e4f259a9583924e1bb13857f17e1..eca151da93305c8d818f81036e0ebaeeb724b977 100644 --- a/website/lecturenotes/20220328.md +++ b/website/lecturenotes/20220328.md @@ -2,6 +2,6 @@ ## Anpassungen * AudioTrack verallgemeinern und austauschbar machen -* MusicManagere abstrahieren, damit die Persistenz gekaüselt ist +* MusicManager abstrahieren, damit die Persistenz gekapselt ist * Aufteilung in Packages * Factory mit unterschiedlichen Parametern diff --git a/website/lecturenotes/20220404.md b/website/lecturenotes/20220404.md new file mode 100644 index 0000000000000000000000000000000000000000..7d80ac0d22861c7ad52b595a428727cc29ea7644 --- /dev/null +++ b/website/lecturenotes/20220404.md @@ -0,0 +1 @@ +# Vorlesungsnotizen - 04.04.2022 \ No newline at end of file