AAA06: comment in Act block

Problematic code

def test_a() -> None:
    shopping = ['apples', 'bananas', 'cabbages']

    # Reverse shopping list operates in place
    shopping.reverse()  # act

    assert shopping == ['cabbages', 'bananas', 'apples']

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:

def test_a() -> None:
    """
    Reverse shopping list operates in place
    """
    shopping = ['apples', 'bananas', 'cabbages']

    shopping.reverse()  # act

    assert shopping == ['cabbages', 'bananas', 'apples']

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:

def test_b() -> None:
    # NOTE: the most interesting thing about this test is this comment

    result = 1 + 1

    assert result == 2

Rationale

The Act block carries out a single action on an object. It is the focus of each test. Therefore any comments on this single action are really comments on the test itself and so should be moved to the test docstring.

By placing these important comments in the docstring we can:

• Make it easier to keep the Act block simple.

• Help to distinguish the Act block from the rest of the test.

• Improve the documentation of tests because any important comments and notes are lifted to the top of the test.

Exceptions

Directives in the form of inline comments are OK, for example:

• Marking the Act block:

  shopping.reverse()  # act
  

• Marking lines in the action for linting reasons:

  result = shopping.reverse()  # type: ignore