Skip to content

Commit 3d853ac

Browse files
veitveit
committed
🎨 Improve structure of the cite software section
1 parent ed12049 commit 3d853ac

File tree

5 files changed

+121
-42
lines changed

5 files changed

+121
-42
lines changed

docs/productive/qa/anti-patterns.rst renamed to docs/productive/qa/code-smells.rst

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
..
33
.. SPDX-License-Identifier: BSD-3-Clause
44
5-
Code-Smells und Anti-Patterns
6-
=============================
5+
Code-Smells und Design-Prinzipien
6+
=================================
77

88
Code-Smells sind Codierungsmuster, die darauf hinweisen, dass mit dem Entwurf
99
eines Programms etwas nicht stimmt. Zum Beispiel ist die übermäßige Verwendung
@@ -56,13 +56,15 @@ D – :ref:`dependency-inversion`
5656
Open-Closed-Prinzip
5757
-------------------
5858

59-
Die Entscheidung, ob eine Refaktorierung durchgeführt werden soll, sollte davon
60-
abhängen, ob euer Code bereits *offen* für neue Anforderungen ist, ohne hierfür
61-
bestehenden Code ändern zu müssen. Refaktorierungen sollten nicht mit dem
62-
Hinzufügen neuer Funktionen vermischt sondern beide Vorgänge voneinander
63-
getrennt werden. Wenn ihr mit einer neuen Anforderung konfrontiert werdet,
64-
ordnet zunächst den vorhandenen Code so um, dass er für die neue Funktion offen
65-
ist, und fügt den neuen Code erst hinzu, wenn dies abgeschlossen ist.
59+
Die Entscheidung, ob eine Refaktorierung überhaupt durchgeführt werden soll,
60+
sollte davon abhängen, ob euer Code bereits *offen* für neue Anforderungen ist.
61+
*Offen* meint hier, dass euer Code offen für Erweiterungen sein sollte, ohne
62+
hierfür jedoch bestehenden Code ändern zu müssen. Refaktorierungen sollten nicht
63+
mit dem Hinzufügen neuer Funktionen vermischt werden. Stattdessen sollten diese
64+
beiden Vorgänge voneinander getrennt werden. Wenn ihr mit einer neuen
65+
Anforderung konfrontiert werdet, ordnet zunächst den vorhandenen Code so um,
66+
dass er für die neue Funktion offen ist, und fügt den neuen Code erst hinzu,
67+
wenn dies abgeschlossen ist.
6668

6769
Unter Refaktorierung versteht man den Prozess, ein Softwaresystem so zu
6870
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.
8183
* habt ihr den Code versehentlich beschädigt,
8284
* oder die vorhandenen Tests sind fehlerhaft.
8385

86+
Das Open-Closed-Prinzip entspricht dem *O* in den `SOLID-Prinzipien
87+
<https://de.wikipedia.org/wiki/Prinzipien_objektorientierten_Designs#SOLID-Prinzipien>`_:
88+
89+
S – :ref:`single-responsibility`
90+
Die Methoden einer Klasse sollten auf einen einzigen Zweck ausgerichtet
91+
sein.
92+
O – :ref:`open-closed`
93+
Objekte sollten offen für Erweiterungen, aber geschlossen für Änderungen
94+
sein.
95+
L – :ref:`liskov-substitution`
96+
Unterklassen sollten durch ihre Oberklassen substituierbar sein.
97+
I – :ref:`interface-segregation`
98+
Objekte sollten nicht von Methoden abzuhängen, die sie nicht verwenden.
99+
D – :ref:`dependency-inversion`
100+
Abstraktionen sollten nicht von Details abhängen.
101+
84102
.. _single-responsibility:
85103

86104
Single-Responsibility-Prinzip
@@ -150,13 +168,6 @@ werden als
150168
Typische Code-Smells in Python
151169
------------------------------
152170

153-
.. seealso::
154-
* `Effective Python <https://effectivepython.com/>`_
155-
by Brett Slatkin
156-
* `When Python Practices Go Wrong
157-
<https://rhodesmill.org/brandon/slides/2019-11-codedive/>`_
158-
by Brandon Rhodes
159-
160171
Funktionen, die Objekte sein sollten
161172
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162173

@@ -313,3 +324,10 @@ Code reduzieren mit ``dataclasses`` und ``attrs``
313324
ist ein Python-Paket, das es schon viel länger als ``dataclasses`` gibt,
314325
umfangreicher ist und auch mit älteren Versionen von Python verwendet werden
315326
kann.
327+
328+
.. seealso::
329+
* `Effective Python <https://effectivepython.com/>`_
330+
by Brett Slatkin
331+
* `When Python Practices Go Wrong
332+
<https://rhodesmill.org/brandon/slides/2019-11-codedive/>`_
333+
by Brandon Rhodes

‎docs/productive/qa/flake8.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,11 @@
55
``flake8``
66
==========
77

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

1314
Installation
1415
------------

‎docs/productive/qa/index.rst‎

Lines changed: 72 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,36 +5,92 @@
55
Code-Qualität und Komplexität überprüfen und verbessern
66
=======================================================
77

8-
Bevor ihr mit dem Refactoring beginnt, solltet ihr die Komplexität eures Codes
9-
messen. Im Folgenden möchte ich euch einige Werkzeuge und Konzepte vorstellen,
10-
die die Komplexität eures Codes überprüfen und die Wartung und Pflege von
11-
Python-Paketen und anderem Quellcode vereinfachen. Häufig lässt sich zusammen
12-
mit dem :doc:`../git/advanced/hooks/pre-commit` die Code-Qualität auch automatisiert
13-
überprüfen und verbessern.
8+
Wenn die Qualität von Software vernachlässigt wird, führt dies schnell zu
9+
überflüssigem Code, auch *Cruft* genannt, der dann die Weiterentwicklung von
10+
Funktionen bremst. Das passiert auch großen Teams, die keine Zeit für die Pflege
11+
einer hohen Codequalität aufwenden dürfen. Eine hohe Codequalität reduziert
12+
Cruft auf ein Minimum und ermöglicht es dem Team, Funktionen mit weniger
13+
Aufwand, Zeit und Kosten hinzuzufügen. Es gibt zwar einige Indikatoren, die zur
14+
Messung der internen Qualität herangezogen werden können, diese können jedoch
15+
nur einen ersten Hinweis auf die weitere Produktivität geben. Eine kürzlich
16+
durchgeführte `Studie <https://arxiv.org/abs/2203.04374>`_ zeigt jedoch, dass
17+
die Korrektur von Code mit niedriger Qualität mehr als doppelt so lange dauert
18+
wie die von Code mit hoher Qualität, und dass die Fehlerdichte bei Code mit
19+
niedriger Qualität 15 Mal höher ist.
20+
21+
Im Folgenden zeige ich euch einige :doc:`code-smells` und dann einige Tools, mit
22+
denen ihr automatisierte statische Analysen durchführen und den Code neu
23+
formatieren könnt. Einige dieser Tools könnt ihr sowohl in euren Editor wie auch
24+
über das :doc:`../git/advanced/hooks/pre-commit` einbinden. Zum Schluss stelle
25+
ich euch noch :doc:`rope` vor, ein Tool, das euch bei Refactorings unterstützt.
1426

1527
.. seealso::
1628
* `PyCQA Meta Documentation <https://meta.pycqa.org/en/latest/>`_
1729
* `github.com/PyCQA <https://github.com/PyCQA>`_
1830

31+
32+
.. toctree::
33+
:hidden:
34+
:titlesonly:
35+
:maxdepth: 0
36+
37+
code-smells
38+
1939
Checker
2040
-------
2141

42+
:doc:`flake8`
43+
ist ein Wrapper um `PyFlakes <https://pypi.org/project/pyflakes/>`_,
44+
`pycodestyle <https://pypi.org/project/pycodestyle/>`_ und `McCabe
45+
<https://pypi.org/project/mccabe/>`_. Eine automatische Formatierung,
46+
:abbr:`(zum Beispiel)` mit :doc:`black`, ist jedoch noch bequemer.
47+
:doc:`mypy`
48+
ist ein statischer Typ-Checker.
49+
:doc:`pytype`
50+
ist ein statisches Analysewerkzeug, das Typen aus eurem Python-Code
51+
ableitet, ohne dass Typ-Annotationen erforderlich sind.
52+
:doc:`wily`
53+
ist ein Kommandozeilenwerkzeug zur Überprüfung der Komplexität von
54+
Python-Code in Tests und Anwendungen.
55+
:doc:`pystra`
56+
analysiert die strukturelle Zuverlässigkeit von Python-Code und fasst sie in
57+
einem Bericht zusammen.
58+
:doc:`pysa`
59+
führt eine `Taint <https://en.wikipedia.org/wiki/Taint_checking>`_-Analyse
60+
durch, um potenzielle Sicherheitsprobleme zu identifizieren. Pysa verfolgt
61+
Datenströme von ihrem Ursprung bis zu ihrem Endpunkt und identifiziert
62+
verwundbaren Code.
63+
:doc:`manifest`
64+
ist ein Werkzeug, mit dem ihr schnell überprüfen könnt, ob die Datei
65+
:ref:`python-basics:manifest-in` für Python-Pakete vollständig ist.
66+
2267
.. toctree::
23-
:maxdepth: 1
68+
:hidden:
69+
:titlesonly:
70+
:maxdepth: 0
2471

2572
flake8
26-
manifest
2773
mypy
2874
pytype
2975
wily
30-
pyre
76+
pystra
3177
pysa
78+
manifest
3279

3380
Formatter
3481
---------
3582

83+
:doc:`black`
84+
formatiert euren Code in ein schönes und deterministisches Format.
85+
:doc:`isort`
86+
formatiert eure ``import``-Anweisungen in separaten und sortierten Blöcken.
87+
:doc:`prettier`
88+
bietet automatische Formatierer für andere Dateitypen.
89+
3690
.. toctree::
37-
:maxdepth: 1
91+
:hidden:
92+
:titlesonly:
93+
:maxdepth: 0
3894

3995
black
4096
isort
@@ -43,10 +99,14 @@ Formatter
4399
Refactoring
44100
-----------
45101

102+
:doc:`rope`
103+
ist eine Python-Bibliothek zum Refactoring.
104+
46105
.. toctree::
47-
:maxdepth: 1
106+
:hidden:
107+
:titlesonly:
108+
:maxdepth: 0
48109

49-
anti-patterns
50110
rope.ipynb
51111

52112
.. seealso::

docs/productive/qa/pyre.rst renamed to docs/productive/qa/pystra.rst

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,24 @@
22
..
33
.. SPDX-License-Identifier: BSD-3-Clause
44
5-
PyRe
6-
====
5+
Pystra
6+
======
77

8-
PyRe (Python Reliability) analysiert die strukturelle Zuverlässigkeit von
9-
Python-Code und fasst sie in einem Report zusammen. Aktuell werden jedoch nur
10-
Zufälligkeitsmethoden erster Ordnung unterstützt wie Crude
11-
Monte-Carlo-Simulation und Importance Sampling.
8+
:abbr:`Pystra (Python Structural Reliability Analysis)` analysiert die
9+
strukturelle Zuverlässigkeit von Python-Code und fasst sie in einem Report
10+
zusammen. Aktuell werden jedoch nur Zufälligkeitsmethoden erster Ordnung
11+
unterstützt wie *Crude Monte-Carlo*-Simulation und *Importance Sampling*.
1212

1313
.. seealso::
14-
* `Docs <https://hackl.science/pyre/>`_
15-
* `GitHub <https://github.com/hackl/pyre>`_
14+
* `Docs <http://pystra.github.io/pystra/>`_
15+
* `GitHub <https://github.com/pystra/pystra>`_
1616

1717
Installation
1818
------------
1919

2020
.. code-block:: console
2121
22-
$ pipenv install git+git://github.com/hackl/pyre.git
22+
$ pipenv install pystra
2323
2424
Zuverlässigkeitsanalyse
2525
-----------------------

‎docs/productive/qa/rope.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@
209209
"id": "twelve-pixel",
210210
"metadata": {},
211211
"source": [
212-
"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)."
212+
"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)."
213213
]
214214
}
215215
],

0 commit comments

Comments
 (0)