Executable documentation encodes system knowledge in artifacts that can be run or checked, so incorrect or outdated guidance is more likely to be caught. Unlike a wiki page that can quietly go stale, a test or setup script can fail when it no longer matches the system. section 13.5
Use it to make important knowledge easier to find and verify:
- Name tests for business rules and assert the permitted and rejected outcomes. section 13.4.2
- Make setup scripts, test suites, and deployment pipelines part of onboarding guidance; use architectural decision records to explain why the system is designed as it is. section 13.5
Listing 13.2 Tests as executable documentation of business rules
def test_refund_exceeding_original_amount_is_rejected():
order = create_order(amount_cents=5000)
result = process_refund(order, refund_cents=5001)
assert result.status == "REJECTED"
assert result.reason == "Refund exceeds original transaction amount"
def test_partial_refund_reduces_remaining_refundable_amount():
order = create_order(amount_cents=5000)
process_refund(order, refund_cents=2000)
result = process_refund(order, refund_cents=3001)
assert result.status == "REJECTED"
assert result.reason == "Refund exceeds remaining refundable amount"The refund tests state two business rules through descriptive names and assertions: refunds cannot exceed the original or remaining refundable amount. section 13.4.2
