git, Dokumentation, Clean Code

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/se3sose2023projekt)

---

# 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/se3sose2023projekt/-/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 durchführen

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/

---
# 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.
* Nutzen von _Feature Flags_: Neue Funktionen werden nach und nach freigeschaltet.

---
# `merge` requests in GitLab

* GitHub: `pull requests`
* Kann Bestandteil eines Reviewprozesses sein

> [Demo im Repo](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2023projekt)

---
# `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.

---

# `git stash`

* Zwischenspeichern ohne Commit
* Notwenig wenn auf einen anderen Branch gewechselt werden muss, man aber keinen Commit machen möchte
* Meistens notwendig, wenn es zu Konflikten zwischen zwei Branches geben würde

```bash
# Annahme: Arbeit auf einem Branch (hier: 'my-branch')
git stash # Zwischenspeichern der Änderungen. Alternativ:
git stash -u # Beeinhaltet auch 'untracked' Dateien

git checkout main # Wechseln auf main

git checkout my-branch # Zwischengespeicherter Code ist noch nicht schichtbar

git stash pop # Wiederherstellen des Zwischenspeichers
```

---
class: center, middle
# Dokumentation & Issue Management

---
# Dokumentationsformen

* Doku am Code (`javadoc`, s. [Dokumentation](https://www.oracle.com/de/technical-resources/articles/java/javadoc-tool.html)), sofern notwendig
* Doku im Repository
  * Readme, z.B. mit Anleitung wie das Programm gestartet werden kann
  * Changelog
* Technische Dokumentation
  * Diagramme mit `mermaid` möglich: https://mermaid-js.github.io/mermaid/#/
* Enduser Doku

> Schulungen mitdenken!

---
# Nutzen eines Wikis

> [Demo im Repo](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2023projekt)

# Nutzen von Milestones

> [Demo im Repo](https://gitlab.mi.hdm-stuttgart.de/jordine/se3sose2023projekt)
---
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
* **O**pen Closed Princple: 
  * Offen für Erweiterung, geschlossen für Veränderung
* **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

> Arbeit am Demoprojekt

---
# 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

---
# Weitere Informationen

* "GitHub git Spickzettel", github.com, https://training.github.com/downloads/de/github-git-cheat-sheet/
* "Git-flow-Workflow", Atlassian, https://www.atlassian.com/de/git/tutorials/comparing-workflows/gitflow-workflow
* "Trunk Based Development: Five-minute overview": trunkbaseddevelopment.com, https://trunkbaseddevelopment.com/5-min-overview/
* "Introduction to Git workflows", gitlab.com, https://docs.gitlab.com/ee/topics/gitlab_flow.html
* "Make a README", makeareadme.com, https://www.makeareadme.com
* "Clean Code: A Handbook of Agile Software Craftsmanship", Robert C. Martin, Prentice Hall, 2008