Nobody has ever passed the second argument

# Self-authored for the EML case corpus (no external origin). The function takes
# an optional second argument. How many call sites pass it is computed below,
# and so is what it costs to keep.
#
# Adding the parameter was right. A caller genuinely might need to override the
# behaviour, adding it later would be a breaking change for anyone who had
# already written a positional call, and it is optional so no existing caller
# had to change. This is the standard advice and it was followed.
#
# A parameter nobody passes is a branch nobody runs, and unlike dead code it
# cannot be deleted by a linter, because it is reachable in principle and part
# of the published signature. It is carried by every change to the function.
#
# The call sites and the maintenance cost are counted separately.

# [parameter, call sites that pass it, call sites total, branches it adds, times it appeared in a review]
[["strict", 0, 47, 2, 6], ["encoding", 3, 47, 1, 1], ["timeout_ms", 12, 47, 1, 0], ["legacy_mode", 0, 47, 3, 9], ["on_error", 0, 47, 2, 4]] => params

len(params) => n
47 => call_sites

"parameters on the signature : " + str(n) ^0
"call sites : " + str(call_sites) ^0
"" ^0
"parameter      passed by   branches   review mentions" ^0
0 => never_passed
0 => dead_branches
0 => review_cost
for p in params:
    "  " + p[0] + "   " + str(p[1]) + " of " + str(p[2]) + "     " + str(p[3]) + "          " + str(p[4]) ^0
    if p[1] == 0:
        never_passed + 1 => never_passed
        dead_branches + p[3] => dead_branches
        review_cost + p[4] => review_cost
"" ^0

"parameters no call site has ever passed : " + str(never_passed) + " of " + str(n) ^0
if never_passed > 0:
    "  branches behind them : " + str(dead_branches) ^0
    "  times they came up in review anyway : " + str(review_cost) ^0
"" ^0

# ---- what the unpassed ones cost ----

0 => total_branches
for p in params:
    total_branches + p[3] => total_branches
"branches in the function : " + str(total_branches) ^0
if total_branches > 0:
    "  reachable from a real call site : " + str(total_branches - dead_branches) ^0
    "  reachable only in principle      : " + str(dead_branches) + ", which is " + str(int(dead_branches * 100 / total_branches)) + "%" ^0
"" ^0

"what a change to this function has to consider" ^0
"  behaviours a caller depends on : " + str(total_branches - dead_branches) ^0
"  behaviours that must be preserved anyway : " + str(dead_branches) ^0
"  the second group has no caller to break and cannot be shown to work" ^0
"" ^0

# ---- what is known about the unpassed branches ----

"evidence available for each kind of branch" ^0
"  passed by a call site : production traffic, every day" ^0
"  passed only by a test : whatever the test asserts" ^0
"  never passed at all   : the code reads correctly" ^0
"  the third is the same evidence the code had on the day it was written" ^0
"" ^0

# ---- the review cost, which is the visible one ----

0 => total_mentions
for p in params:
    total_mentions + p[4] => total_mentions
"review mentions across all parameters : " + str(total_mentions) ^0
if review_cost > 0:
    "  of those, about parameters nobody passes : " + str(review_cost) + ", which is " + str(int(review_cost * 100 / total_mentions)) + "%" ^0
    "  a reviewer has to reason about them because they are in the signature," ^0
    "  and no reviewer can check them against a caller" ^0
"" ^0

# ---- removing one ----

"removing a parameter no call site passes" ^0
"  callers that break : 0, by the count above" ^0
"  branches removed   : " + str(dead_branches) ^0
"  what stops it      : it is published, so removal is a breaking change to" ^0
"  an interface rather than to any caller" ^0
"  the parameter costs nothing to any caller and cannot be removed for the" ^0
"  sake of the callers it has none of" ^0
"" ^0

# ---- the control: a parameter that is used ----
#
# Where a parameter has call sites, its branches are exercised by traffic and
# the reasoning about them is anchored to something.

for p in params:
    if p[1] > 0:
        if p[1] > 10:
            "control - " + p[0] + ", passed by " + str(p[1]) + " of " + str(p[2]) + " call sites" ^0
            "  its branch runs in production, so a change to it is caught by the" ^0
            "  callers rather than by a reviewer imagining them" ^0
"" ^0

"The parameter was added for a real reason and adding it later would have" ^0
"broken callers. Nothing has passed it, so what is known about the code" ^0
"behind it is what was known the day it was written." ^0

params = [["strict", 0, 47, 2, 6], ["encoding", 3, 47, 1, 1], ["timeout_ms", 12, 47, 1, 0], ["legacy_mode", 0, 47, 3, 9], ["on_error", 0, 47, 2, 4]]
n = len(params)
call_sites = 47
print("parameters on the signature : " + str(n))
print("call sites : " + str(call_sites))
print("")
print("parameter      passed by   branches   review mentions")
never_passed = 0
dead_branches = 0
review_cost = 0
for p in params:
    print("  " + p[0] + "   " + str(p[1]) + " of " + str(p[2]) + "     " + str(p[3]) + "          " + str(p[4]))
    if p[1] == 0:
        never_passed = never_passed + 1
        dead_branches = dead_branches + p[3]
        review_cost = review_cost + p[4]
print("")
print("parameters no call site has ever passed : " + str(never_passed) + " of " + str(n))
if never_passed > 0:
    print("  branches behind them : " + str(dead_branches))
    print("  times they came up in review anyway : " + str(review_cost))
print("")
total_branches = 0
for p in params:
    total_branches = total_branches + p[3]
print("branches in the function : " + str(total_branches))
if total_branches > 0:
    print("  reachable from a real call site : " + str(total_branches - dead_branches))
    print("  reachable only in principle      : " + str(dead_branches) + ", which is " + str(int(dead_branches * 100 / total_branches)) + "%")
print("")
print("what a change to this function has to consider")
print("  behaviours a caller depends on : " + str(total_branches - dead_branches))
print("  behaviours that must be preserved anyway : " + str(dead_branches))
print("  the second group has no caller to break and cannot be shown to work")
print("")
print("evidence available for each kind of branch")
print("  passed by a call site : production traffic, every day")
print("  passed only by a test : whatever the test asserts")
print("  never passed at all   : the code reads correctly")
print("  the third is the same evidence the code had on the day it was written")
print("")
total_mentions = 0
for p in params:
    total_mentions = total_mentions + p[4]
print("review mentions across all parameters : " + str(total_mentions))
if review_cost > 0:
    print("  of those, about parameters nobody passes : " + str(review_cost) + ", which is " + str(int(review_cost * 100 / total_mentions)) + "%")
    print("  a reviewer has to reason about them because they are in the signature,")
    print("  and no reviewer can check them against a caller")
print("")
print("removing a parameter no call site passes")
print("  callers that break : 0, by the count above")
print("  branches removed   : " + str(dead_branches))
print("  what stops it      : it is published, so removal is a breaking change to")
print("  an interface rather than to any caller")
print("  the parameter costs nothing to any caller and cannot be removed for the")
print("  sake of the callers it has none of")
print("")
for p in params:
    if p[1] > 0:
        if p[1] > 10:
            print("control - " + p[0] + ", passed by " + str(p[1]) + " of " + str(p[2]) + " call sites")
            print("  its branch runs in production, so a change to it is caught by the")
            print("  callers rather than by a reviewer imagining them")
print("")
print("The parameter was added for a real reason and adding it later would have")
print("broken callers. Nothing has passed it, so what is known about the code")
print("behind it is what was known the day it was written.")

parameters on the signature : 5
call sites : 47

parameter      passed by   branches   review mentions
  strict   0 of 47     2          6
  encoding   3 of 47     1          1
  timeout_ms   12 of 47     1          0
  legacy_mode   0 of 47     3          9
  on_error   0 of 47     2          4

parameters no call site has ever passed : 3 of 5
  branches behind them : 7
  times they came up in review anyway : 19

branches in the function : 9
  reachable from a real call site : 2
  reachable only in principle      : 7, which is 77%

what a change to this function has to consider
  behaviours a caller depends on : 2
  behaviours that must be preserved anyway : 7
  the second group has no caller to break and cannot be shown to work

evidence available for each kind of branch
  passed by a call site : production traffic, every day
  passed only by a test : whatever the test asserts
  never passed at all   : the code reads correctly
  the third is the same evidence the code had on the day it was written

review mentions across all parameters : 20
  of those, about parameters nobody passes : 19, which is 95%
  a reviewer has to reason about them because they are in the signature,
  and no reviewer can check them against a caller

removing a parameter no call site passes
  callers that break : 0, by the count above
  branches removed   : 7
  what stops it      : it is published, so removal is a breaking change to
  an interface rather than to any caller
  the parameter costs nothing to any caller and cannot be removed for the
  sake of the callers it has none of

control - timeout_ms, passed by 12 of 47 call sites
  its branch runs in production, so a change to it is caught by the
  callers rather than by a reviewer imagining them

The parameter was added for a real reason and adding it later would have
broken callers. Nothing has passed it, so what is known about the code
behind it is what was known the day it was written.

Trace event types