🎨 Improve structure of the code quality 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 and Anti-Patterns
-=============================
+Code-Smells and design principles
+=================================
 
 Code smells are coding patterns that indicate that something is wrong with the
 design of a programme. For example, the overuse of isinstance checks against
@@ -51,13 +51,13 @@ D – :ref:`dependency-inversion`
 Open-closed principle
 ---------------------
 
-The decision as to whether refactoring should be carried out should depend on
-whether your code is already open to new requirements without having to change
+The decision as to whether refactoring should be carried out at all should
+depend on whether your code is already *open* to new requirements. Open here
+means that your code should be open for extensions without having to change
 existing code. Refactorings should not be mixed with the addition of new
-functions, but both processes should be separated from each other. If you are
-confronted with a new requirement, first reorganise the existing code so that it
-is open for the new function and only add the new code once this has been
-completed.
+functions. Instead, these two processes should be kept separate. When faced with
+a new requirement, first reorganise the existing code so that it is open to the
+new function and only add the new code once this has been completed.
 
     Refactoring is the process of changing a software system in such a way that
     it does not alter the external behavior of the code yet improves its
@@ -141,13 +141,6 @@ defined as
 Typical 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
-
 Functions that should be objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -291,5 +284,12 @@ Reduce code with ``dataclasses`` and ``attrs``
        * :pep:`557` – Data Classes
 
 `attrs <https://www.attrs.org/en/stable/>`_
-    is a Python package that has been around much longer than ``dataclasses``, is more
-    comprehensive and can also be used with older versions of Python.
+    is a Python package that has been around much longer than ``dataclasses``,
+    is more comprehensive and can also be used with older versions of 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

docs/productive/qa/flake8.rst

@@ -5,9 +5,11 @@
 ``flake8``
 ==========
 
-`flake8 <https://pypi.org/project/flake8/>`_ ensures that most of your code
-follows :pep:`8`. However, automatic formatting, for example with :doc:`black`,
-is even more convenient. In addition ``flake8`` also checks for unused imports.
+`flake8 <https://pypi.org/project/flake8/>`_ is a wrapper around `PyFlakes
+<https://pypi.org/project/pyflakes/>`_, `pycodestyle
+<https://pypi.org/project/pycodestyle/>`_ and `McCabe
+<https://pypi.org/project/mccabe/>`_. However, automatic formatting, for example
+with :doc:`black`, is even more convenient.
 
 Installation
 ------------

docs/productive/qa/index.rst

@@ -5,36 +5,88 @@
 Check and improve code quality and complexity
 =============================================
 
-Before you start refactoring, you should measure the complexity of your code. In
-the following, I would like to introduce you to some tools and concepts that
-check the complexity of your code and simplify the maintenance and care of
-Python packages and other source code. Often, together with
-:doc:`../git/advanced/hooks/pre-commit`, the code quality can also be checked and
-improved automatically.
+If the quality of software is neglected, this quickly leads to superfluous code,
+also known as cruft. This then slows down the further development of functions.
+This also happens to great teams who are not allowed to spend time maintaining
+high code quality. High code quality reduces cruft to a minimum and allows the
+team to add features with less effort, time and cost. Although there are some
+indicators that can be used to measure internal quality, these can only provide
+an initial indication of further productivity. However, a recent `study
+<https://arxiv.org/abs/2203.04374>`_ indicates that low quality code took more
+than twice as long to fix as high quality code, and that low quality code had a
+15 times higher defect density.
+
+In the following, I will show you some :doc:`code-smells` and then some tools
+with which you can perform automated static analyses and reformat the code. You
+can also easily integrate some of these tools via the
+:doc:`../git/advanced/hooks/pre-commit`. Finally, I’ll introduce you to
+:doc:`rope`, a tool that supports you with refactorings.
 
 .. seealso::
    * `PyCQA Meta Documentation <https://meta.pycqa.org/>`_
    * `github.com/PyCQA <https://github.com/PyCQA>`_
 
+.. toctree::
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
+
+   code-smells
+
 Checker
 -------
 
+:doc:`flake8`
+    is a wrapper around `PyFlakes <https://pypi.org/project/pyflakes/>`_,
+    `pycodestyle <https://pypi.org/project/pycodestyle/>`_ and `McCabe
+    <https://pypi.org/project/mccabe/>`_. However, automatic formatting, for
+    example with :doc:`black`, is even more convenient.
+:doc:`mypy`
+    is a static type checker.
+:doc:`pytype`
+    is a static analysis tool that derives types from your Python code without
+    the need for type annotations.
+:doc:`wily`
+    is a command line tool for checking the complexity of Python code in tests
+    and applications.
+:doc:`pystra`
+    analyses the structural reliability of Python code and summarises it in a
+    report.
+:doc:`pysa`
+    performs `taint <https://en.wikipedia.org/wiki/Taint_checking>`_ analysis to
+    identify potential security problems. Pysa traces data streams from their
+    origin to their endpoint and identifies vulnerable code.
+:doc:`manifest`
+    is a tool with which you can quickly check whether the file
+    :ref:`python-basics:manifest-in` for Python packages is complete.
+
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
 
    flake8
-   manifest
    mypy
    pytype
    wily
    pystra
    pysa
+   manifest
 
 Formatter
 ---------
 
+:doc:`black`
+    formats your code in a nice and deterministic format.
+:doc:`isort`
+    formats your ``import`` statements in separate and sorted blocks.
+:doc:`prettier`
+    offers automatic formatters for other file types.
+
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
 
    black
    isort
@@ -43,13 +95,16 @@ Formatter
 Refactoring
 -----------
 
+:doc:`rope`
+    is a Python refactoring library.
+
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+   :maxdepth: 0
 
-   anti-patterns
    rope.ipynb
 
-
 .. seealso::
    * `Martin Fowler: Refactoring
      <https://www.mitp.de/IT-WEB/Software-Entwicklung/Refactoring.html>`_