🎨 Improve structure of the cite software section

docs/productive/qa/anti-patterns.rst → docs/productive/qa/code-smells.rst

@@ -2,8 +2,8 @@
 ..
 .. SPDX-License-Identifier: BSD-3-Clause
 
-Code-Smells und Anti-Patterns
-=============================
+Code-Smells und Design-Prinzipien
+=================================
 
 Code-Smells sind Codierungsmuster, die darauf hinweisen, dass mit dem Entwurf
 eines Programms etwas nicht stimmt. Zum Beispiel ist die übermäßige Verwendung
@@ -56,13 +56,15 @@ D – :ref:`dependency-inversion`
 Open-Closed-Prinzip
 -------------------
 
-Die Entscheidung, ob eine Refaktorierung durchgeführt werden soll, sollte davon
-abhängen, ob euer Code bereits *offen* für neue Anforderungen ist, ohne hierfür
-bestehenden Code ändern zu müssen. Refaktorierungen sollten nicht mit dem
-Hinzufügen neuer Funktionen vermischt sondern beide Vorgänge voneinander
-getrennt werden. Wenn ihr mit einer neuen Anforderung konfrontiert werdet,
-ordnet zunächst den vorhandenen Code so um, dass er für die neue Funktion offen
-ist, und fügt den neuen Code erst hinzu, wenn dies abgeschlossen ist.
+Die Entscheidung, ob eine Refaktorierung überhaupt durchgeführt werden soll,
+sollte davon abhängen, ob euer Code bereits *offen* für neue Anforderungen ist.
+*Offen* meint hier, dass euer Code offen für Erweiterungen sein sollte, ohne
+hierfür jedoch bestehenden Code ändern zu müssen. Refaktorierungen sollten nicht
+mit dem Hinzufügen neuer Funktionen vermischt werden. Stattdessen sollten diese
+beiden Vorgänge voneinander getrennt werden. Wenn ihr mit einer neuen
+Anforderung konfrontiert werdet, ordnet zunächst den vorhandenen Code so um,
+dass er für die neue Funktion offen ist, und fügt den neuen Code erst hinzu,
+wenn dies abgeschlossen ist.
 
     Unter Refaktorierung versteht man den Prozess, ein Softwaresystem so zu
     verändern, dass das äußere Verhalten des Codes nicht verändert, aber seine
@@ -81,6 +83,22 @@ ist, und fügt den neuen Code erst hinzu, wenn dies abgeschlossen ist.
    * habt ihr den Code versehentlich beschädigt,
    * oder die vorhandenen Tests sind fehlerhaft.
 
+Das Open-Closed-Prinzip entspricht dem *O* in den `SOLID-Prinzipien
+<https://de.wikipedia.org/wiki/Prinzipien_objektorientierten_Designs#SOLID-Prinzipien>`_:
+
+S – :ref:`single-responsibility`
+    Die Methoden einer Klasse sollten auf einen einzigen Zweck ausgerichtet
+    sein.
+O – :ref:`open-closed`
+    Objekte sollten offen für Erweiterungen, aber geschlossen für Änderungen
+    sein.
+L – :ref:`liskov-substitution`
+    Unterklassen sollten durch ihre Oberklassen substituierbar sein.
+I – :ref:`interface-segregation`
+    Objekte sollten nicht von Methoden abzuhängen, die sie nicht verwenden.
+D – :ref:`dependency-inversion`
+    Abstraktionen sollten nicht von Details abhängen.
+
 .. _single-responsibility:
 
 Single-Responsibility-Prinzip
@@ -150,13 +168,6 @@ werden als
 Typische Code-Smells in Python
 ------------------------------
 
-.. seealso::
-   * `Effective Python <https://effectivepython.com/>`_
-     by Brett Slatkin
-   * `When Python Practices Go Wrong
-     <https://rhodesmill.org/brandon/slides/2019-11-codedive/>`_
-     by Brandon Rhodes
-
 Funktionen, die Objekte sein sollten
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -313,3 +324,10 @@ Code reduzieren mit ``dataclasses`` und ``attrs``
     ist ein Python-Paket, das es schon viel länger als ``dataclasses`` gibt,
     umfangreicher ist und auch mit älteren Versionen von Python verwendet werden
     kann.
+
+.. seealso::
+   * `Effective Python <https://effectivepython.com/>`_
+     by Brett Slatkin
+   * `When Python Practices Go Wrong
+     <https://rhodesmill.org/brandon/slides/2019-11-codedive/>`_
+     by Brandon Rhodes

docs/productive/qa/flake8.rst

@@ -5,10 +5,11 @@
 ``flake8``
 ==========
 
-`flake8 <https://pypi.org/project/flake8/>`_ stellt sicher, dass euer Code
-größtenteils :pep:`8` folgt. Eine automatische Formatierung, :abbr:`z.B. (zum
-Beispiel)` mit :doc:`black`, ist jedoch noch komfortabler. Zudem prüft
-``flake8`` auf nicht verwendete Importe.
+`flake8 <https://pypi.org/project/flake8/>`_ ist ein Wrapper um `PyFlakes
+<https://pypi.org/project/pyflakes/>`_, `pycodestyle
+<https://pypi.org/project/pycodestyle/>`_ und `McCabe
+<https://pypi.org/project/mccabe/>`_. Eine automatische Formatierung,
+:abbr:`z.B. (zum Beispiel)` mit :doc:`black`, ist jedoch noch komfortabler.
 
 Installation
 ------------

docs/productive/qa/index.rst

@@ -5,36 +5,91 @@
 Code-Qualität und Komplexität überprüfen und verbessern
 =======================================================
 
-Bevor ihr mit dem Refactoring beginnt, solltet ihr die Komplexität eures Codes
-messen. Im Folgenden möchte ich euch einige Werkzeuge und Konzepte vorstellen,
-die die Komplexität eures Codes überprüfen und die Wartung und Pflege von
-Python-Paketen und anderem Quellcode vereinfachen. Häufig lässt sich zusammen
-mit dem :doc:`../git/advanced/hooks/pre-commit` die Code-Qualität auch automatisiert
-überprüfen und verbessern.
+Wenn die Qualität von Software vernachlässigt wird, führt dies schnell zu
+überflüssigem Code, auch *Cruft* genannt, der dann die Weiterentwicklung von
+Funktionen bremst. Das passiert auch großen Teams, die keine Zeit für die Pflege
+einer hohen Codequalität aufwenden dürfen. Eine hohe Codequalität reduziert
+Cruft auf ein Minimum und ermöglicht es dem Team, Funktionen mit weniger
+Aufwand, Zeit und Kosten hinzuzufügen. Es gibt zwar einige Indikatoren, die zur
+Messung der internen Qualität herangezogen werden können, diese können jedoch
+nur einen ersten Hinweis auf die weitere Produktivität geben. Eine kürzlich
+durchgeführte `Studie <https://arxiv.org/abs/2203.04374>`_ zeigt jedoch, dass
+die Korrektur von Code mit niedriger Qualität mehr als doppelt so lange dauert
+wie die von Code mit hoher Qualität, und dass die Fehlerdichte bei Code mit
+niedriger Qualität 15 Mal höher ist.
+
+Im Folgenden zeige ich euch einige :doc:`code-smells` und dann einige Tools, mit
+denen ihr automatisierte statische Analysen durchführen und den Code neu
+formatieren könnt. Einige dieser Tools könnt ihr sowohl in euren Editor wie auchüber das :doc:`../git/advanced/hooks/pre-commit` einbinden. Zum Schluss stelle
+ich euch noch :doc:`rope` vor, ein Tool, das euch bei Refactorings unterstützt.
 
 .. seealso::
    * `PyCQA Meta Documentation <https://meta.pycqa.org/en/latest/>`_
    * `github.com/PyCQA <https://github.com/PyCQA>`_
 
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
+
+   code-smells
+
 Checker
 -------
 
+:doc:`flake8`
+    ist ein Wrapper um `PyFlakes <https://pypi.org/project/pyflakes/>`_,
+    `pycodestyle <https://pypi.org/project/pycodestyle/>`_ und `McCabe
+    <https://pypi.org/project/mccabe/>`_. Eine automatische Formatierung,
+    :abbr:`(zum Beispiel)` mit :doc:`black`, ist jedoch noch bequemer.
+:doc:`mypy`
+    ist ein statischer Typ-Checker.
+:doc:`pytype`
+    ist ein statisches Analysewerkzeug, das Typen aus eurem Python-Code
+    ableitet, ohne dass Typ-Annotationen erforderlich sind.
+:doc:`wily`
+    ist ein Kommandozeilenwerkzeug zur Überprüfung der Komplexität von
+    Python-Code in Tests und Anwendungen.
+:doc:`pystra`
+    analysiert die strukturelle Zuverlässigkeit von Python-Code und fasst sie in
+    einem Bericht zusammen.
+:doc:`pysa`
+    führt eine `Taint <https://en.wikipedia.org/wiki/Taint_checking>`_-Analyse
+    durch, um potenzielle Sicherheitsprobleme zu identifizieren. Pysa verfolgt
+    Datenströme von ihrem Ursprung bis zu ihrem Endpunkt und identifiziert
+    verwundbaren Code.
+:doc:`manifest`
+    ist ein Werkzeug, mit dem ihr schnell überprüfen könnt, ob die Datei
+    :ref:`python-basics:manifest-in` für Python-Pakete vollständig ist.
+
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
 
    flake8
-   manifest
    mypy
    pytype
    wily
-   pyre
+   pystra
    pysa
+   manifest
 
 Formatter
 ---------
 
+:doc:`black`
+    formatiert euren Code in ein schönes und deterministisches Format.
+:doc:`isort`
+    formatiert eure ``import``-Anweisungen in separaten und sortierten Blöcken.
+:doc:`prettier`
+    bietet automatische Formatierer für andere Dateitypen.
+
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
 
    black
    isort
@@ -43,10 +98,14 @@ Formatter
 Refactoring
 -----------
 
+:doc:`rope`
+    ist eine Python-Bibliothek zum Refactoring.
+
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
 
-   anti-patterns
    rope.ipynb
 
 .. seealso::

docs/productive/qa/pyre.rst → docs/productive/qa/pystra.rst

@@ -2,24 +2,24 @@
 ..
 .. SPDX-License-Identifier: BSD-3-Clause
 
-PyRe
-====
+Pystra
+======
 
-PyRe (Python Reliability) analysiert die strukturelle Zuverlässigkeit von
-Python-Code und fasst sie in einem Report zusammen. Aktuell werden jedoch nur
-Zufälligkeitsmethoden erster Ordnung unterstützt wie Crude
-Monte-Carlo-Simulation und Importance Sampling.
+:abbr:`Pystra (Python Structural Reliability Analysis)` analysiert die
+strukturelle Zuverlässigkeit von Python-Code und fasst sie in einem Report
+zusammen. Aktuell werden jedoch nur Zufälligkeitsmethoden erster Ordnung
+unterstützt wie *Crude Monte-Carlo*-Simulation und *Importance Sampling*.
 
 .. seealso::
-   * `Docs <https://hackl.science/pyre/>`_
-   * `GitHub <https://github.com/hackl/pyre>`_
+   * `Docs <http://pystra.github.io/pystra/>`_
+   * `GitHub <https://github.com/pystra/pystra>`_
 
 Installation
 ------------
 
 .. code-block:: console
 
-    $ pipenv install git+git://github.com/hackl/pyre.git
+    $ pipenv install pystra
 
 Zuverlässigkeitsanalyse
 -----------------------

docs/productive/qa/rope.ipynb

@@ -209,7 +209,7 @@
    "id": "twelve-pixel",
    "metadata": {},
    "source": [
-    "Rope kann nicht nur zum Umbenennen von Dateien verwendet werden, sondern auch für hunderte anderer Fälle; siehe auch [Rope Refactorings](https://github.com/python-rope/rope/blob/master/docs/overview.rst#refactorings)."
+    "Rope kann nicht nur zum Umbenennen von Dateien verwendet werden, sondern auch für hunderte anderer Fälle; siehe auch [Rope Refactorings](https://rope.readthedocs.io/en/latest/overview.html#refactorings)."
    ]
   }
  ],