diff --git a/docs/productive/qa/anti-patterns.rst b/docs/productive/qa/code-smells.rst similarity index 88% rename from docs/productive/qa/anti-patterns.rst rename to docs/productive/qa/code-smells.rst index dc6c3e7b..05091f9e 100644 --- a/docs/productive/qa/anti-patterns.rst +++ b/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 +`_: + +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 `_ - by Brett Slatkin - * `When Python Practices Go Wrong - `_ - 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 `_ + by Brett Slatkin + * `When Python Practices Go Wrong + `_ + by Brandon Rhodes diff --git a/docs/productive/qa/flake8.rst b/docs/productive/qa/flake8.rst index 9932ed29..250e9231 100644 --- a/docs/productive/qa/flake8.rst +++ b/docs/productive/qa/flake8.rst @@ -5,10 +5,11 @@ ``flake8`` ========== -`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 `_ ist ein Wrapper um `PyFlakes +`_, `pycodestyle +`_ und `McCabe +`_. Eine automatische Formatierung, +:abbr:`z.B. (zum Beispiel)` mit :doc:`black`, ist jedoch noch komfortabler. Installation ------------ diff --git a/docs/productive/qa/index.rst b/docs/productive/qa/index.rst index c48b9f2c..66b27e9f 100644 --- a/docs/productive/qa/index.rst +++ b/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 `_ 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 `_ * `github.com/PyCQA `_ + +.. toctree:: + :hidden: + :titlesonly: + :maxdepth: 0 + + code-smells + Checker ------- +:doc:`flake8` + ist ein Wrapper um `PyFlakes `_, + `pycodestyle `_ und `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 `_-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:: diff --git a/docs/productive/qa/pyre.rst b/docs/productive/qa/pystra.rst similarity index 61% rename from docs/productive/qa/pyre.rst rename to docs/productive/qa/pystra.rst index 7fc349e5..a6607fed 100644 --- a/docs/productive/qa/pyre.rst +++ b/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 `_ - * `GitHub `_ + * `Docs `_ + * `GitHub `_ Installation ------------ .. code-block:: console - $ pipenv install git+git://github.com/hackl/pyre.git + $ pipenv install pystra Zuverlässigkeitsanalyse ----------------------- diff --git a/docs/productive/qa/rope.ipynb b/docs/productive/qa/rope.ipynb index 29b7f74a..903ca9e7 100644 --- a/docs/productive/qa/rope.ipynb +++ b/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)." ] } ],