Add documentation for AAA06 hash-comment resolution, improve examples (…

…#208)

* Upgrade AAA05 bad example

* Build out AAA05 doc #149

* Upgrade AAA06 bad examples

* Add hash-comment example to AAA06 doc

* Fix typing in AAA06 bad example

* Fix mypy errors in AAA05 bad example

* Update Changelog

CHANGELOG.rst

@@ -30,13 +30,20 @@ Added
   <https://github.com/jamescooke/flake8-aaa/pull/204>`_ fixes `issue #185
   <https://github.com/jamescooke/flake8-aaa/issues/185>`_.
 
+* 📕: AAA06 hash comment resolution added to docs. `Pull #208
+  <https://github.com/jamescooke/flake8-aaa/pull/208>`_ fixes `issue #193
+  <https://github.com/jamescooke/flake8-aaa/issues/193>`_.
+
 Changed
 .......
 
 * ⛏️ Release notes updated to use a better method of updating Flake8 version
   strings. Also reduce use of ``vx.y.z`` version strings - use just ``x.y.z``
   instead. `Pull #207 <https://github.com/jamescooke/flake8-aaa/pull/207>`_.
 
+* ⛏️ AAA05 and AAA06 bad examples upgraded. `Pull #208
+  <https://github.com/jamescooke/flake8-aaa/pull/208>`_.
+
 0.13.1_ - 2023/02/27
 --------------------
 

docs/error_codes/AAA05-blank-line-in-block.rst

@@ -1,11 +1,62 @@
 AAA05: blank line in block
---------------------------
+==========================
 
 The only blank lines in the test must be around the Act block making it easy to
 spot. Flake8-AAA found additional blank lines which break up the block's
 layout.
 
-Resolution
-..........
+Problematic code
+----------------
 
-Remove the blank line.
+.. code-block:: python
+
+    def test_a() -> None:
+        x = 3
+
+        y = 4
+
+        result = x**2 + y**2
+
+        assert result == 25
+
+.. code-block:: python
+
+    def test_b() -> None:
+        nothing = None
+
+        with pytest.raises(AttributeError):
+
+            nothing.get_something()
+
+Correct code
+------------
+
+Remove the blank lines.
+
+.. code-block:: python
+
+    def test_a() -> None:
+        x = 3
+        y = 4
+
+        result = x**2 + y**2
+
+        assert result == 25
+
+.. code-block:: python
+
+    def test_b() -> None:
+        nothing = None
+
+        with pytest.raises(AttributeError):
+            nothing.get_something()
+
+Rationale
+---------
+
+Blank lines are essential for dividing up a test. There will usually be just
+two blank lines in each test - one above and one below the Act block. They
+serve to separate the Act block from the rest of the test.
+
+When there are additional blank lines in a test, then the "shape" of the test
+is broken and it is hard to see where the Act block is at a glance.

docs/error_codes/AAA06-comment-in-act-block.rst

@@ -6,20 +6,30 @@ Problematic code
 
 .. code-block:: python
 
-    def test() -> None:
+    def test_a() -> None:
         shopping = ['apples', 'bananas', 'cabbages']
 
         # Reverse shopping list operates in place
         shopping.reverse()  # act
 
         assert shopping == ['cabbages', 'bananas', 'apples']
 
+.. code-block:: python
+
+    def test_b() -> None:
+        # NOTE: the most interesting thing about this test is this comment
+        result = 1 + 1
+
+        assert result == 2
+
 Correct code
 ............
 
+Use docstrings instead of hash-comments:
+
 .. code-block:: python
 
-    def test() -> None:
+    def test_a() -> None:
         """
         Reverse shopping list operates in place
         """
@@ -29,6 +39,27 @@ Correct code
 
         assert shopping == ['cabbages', 'bananas', 'apples']
 
+.. code-block:: python
+
+    def test_b() -> None:
+        """
+        NOTE: the most interesting thing about this test is this comment
+        """
+        result = 1 + 1
+
+        assert result == 2
+
+Separate hash-comment line from Act block with a blank line:
+
+.. code-block:: python
+
+    def test_b() -> None:
+        # NOTE: the most interesting thing about this test is this comment
+
+        result = 1 + 1
+
+        assert result == 2
+
 Rationale
 .........
 

examples/bad/bad_expected.out

@@ -11,16 +11,16 @@ examples/bad/test_aaa03_04.py:4:5: AAA04 expected 1 blank line before Assert blo
 examples/bad/test_aaa03_04.py:9:9: AAA03 expected 1 blank line before Act block, found none
 examples/bad/test_aaa04.py:12:5: AAA04 expected 1 blank line before Assert block, found none
 examples/bad/test_aaa04.py:5:5: AAA04 expected 1 blank line before Assert block, found none
-examples/bad/test_aaa05.py:24:1: AAA05 blank line in block
-examples/bad/test_aaa05.py:35:1: AAA05 blank line in block
-examples/bad/test_aaa05.py:41:1: AAA05 blank line in block
-examples/bad/test_aaa05.py:50:1: AAA05 blank line in block
+examples/bad/test_aaa05.py:22:1: AAA05 blank line in block
+examples/bad/test_aaa05.py:37:1: AAA05 blank line in block
+examples/bad/test_aaa05.py:48:1: AAA05 blank line in block
 examples/bad/test_aaa05.py:54:1: AAA05 blank line in block
-examples/bad/test_aaa05.py:58:1: AAA05 blank line in block
-examples/bad/test_aaa05.py:9:1: AAA05 blank line in block
-examples/bad/test_aaa06.py:19:9: AAA06 comment in Act block
-examples/bad/test_aaa06.py:31:5: AAA06 comment in Act block
-examples/bad/test_aaa06.py:40:9: AAA06 comment in Act block
+examples/bad/test_aaa05.py:63:1: AAA05 blank line in block
+examples/bad/test_aaa05.py:67:1: AAA05 blank line in block
+examples/bad/test_aaa05.py:71:1: AAA05 blank line in block
+examples/bad/test_aaa06.py:16:5: AAA06 comment in Act block
+examples/bad/test_aaa06.py:29:9: AAA06 comment in Act block
+examples/bad/test_aaa06.py:38:5: AAA06 comment in Act block
 examples/bad/test_aaa06.py:9:5: AAA06 comment in Act block
 examples/bad/test_example.py:4:5: AAA03 expected 1 blank line before Act block, found none
 examples/bad/test_noqa_flake8.py:11:17: E225 missing whitespace around operator

examples/bad/test_aaa05.py

@@ -1,46 +1,59 @@
 import pytest
 
 
-def test_arrange():
+@pytest.fixture
+def fixture_a() -> str:
+    return 'A pointless fixture'
+
+
+@pytest.fixture
+def fixture_b() -> str:
+    return 'Another pointless fixture'
+
+
+# --- TESTS ---
+
+
+def test_arrange() -> None:
     """
     Blank line in Arrange Block
     """
     x = 3
 
     y = 4
 
-    result = x ** 2 + y ** 2
+    result = x**2 + y**2
 
     assert result == 25
 
 
-def test_act():
+def test_act() -> None:
     """
     Blank line in Act Block
     """
-    nothing = None
+    empty: list = []
 
-    with pytest.raises(AttributeError):
+    with pytest.raises(IndexError):
 
-        nothing.get_something()
+        empty[0]
 
 
-def test_assert():
+def test_assert() -> None:
     """
     Blank line in Assert Block
     """
-    result = list()
+    result: list = list()
 
     assert not result
 
     assert result.copy() == []
 
 
 def test_all(
-    fixture_a,
+    fixture_a: str,
 
-    fixture_b,
-):
+    fixture_b: str,
+) -> None:
     """
     Blank lines everywhere
 

examples/bad/test_aaa06.py

@@ -3,7 +3,7 @@
 # Example from AAA06 doc:
 
 
-def test() -> None:
+def test_a() -> None:
     shopping = ['apples', 'bananas', 'cabbages']
 
     # Reverse shopping list operates in place
@@ -12,17 +12,24 @@ def test() -> None:
     assert shopping == ['cabbages', 'bananas', 'apples']
 
 
-def test_act():
-    nothing = None
+def test_b() -> None:
+    # NOTE: the most interesting thing about this test is this comment
+    result = 1 + 1
 
-    with pytest.raises(AttributeError):
-        # You can't get something from nothing
-        nothing.get_something()
+    assert result == 2
 
 
 # --- OTHERS ---
 
 
+def test_act() -> None:
+    empty: list = []
+
+    with pytest.raises(IndexError):
+        # You can't get something from an empty bag
+        empty[0]
+
+
 def test_comment_after_act() -> None:
     x = 1
     y = 2
@@ -31,11 +38,3 @@ def test_comment_after_act() -> None:
     # Now check result
 
     assert result == 3
-
-
-def test_raises():
-    nothing = None
-
-    with pytest.raises(AttributeError):
-        # You can't get something from nothing
-        nothing.get_something()

tox.ini

@@ -109,6 +109,7 @@ commands =
         examples/bad/test_aaa03.py \
         examples/bad/test_aaa03_04.py \
         examples/bad/test_aaa04.py \
+        examples/bad/test_aaa05.py \
         examples/bad/test_aaa06.py
 
 # Extra checks on Python 3.8 (and later) files