Enforcement decayed with distance from the author

# Self-authored for the EML case corpus (no external origin). The convention is
# followed closely in the files its author touches and loosely elsewhere. The
# gradient is computed below.
#
# Writing a convention down and then following it yourself is exactly right. The
# author's own files are the demonstration, they are where the reasoning is
# freshest, and a convention nobody follows anywhere is worse than one followed
# somewhere.
#
# Following it elsewhere needs a reader to encounter it, understand why, and
# apply it to a case the document did not enumerate. Each of those attenuates
# with distance from the person who has the reason in their head, and none of
# them attenuates with how much the convention matters in that file.
#
# Compliance is measured per module against that distance.

# [module, hops from the author's team, files, files following the convention, defects it prevents per year]
[["core", 0, 40, 39, 8], ["adjacent", 1, 55, 44, 9], ["same org", 2, 70, 35, 12], ["other org", 3, 90, 18, 15], ["contractor", 4, 30, 3, 6]] => modules

len(modules) => n
0 => files
0 => following
0 => prevented
for m in modules:
    files + m[2] => files
    following + m[3] => following
    prevented + m[4] => prevented

"files in scope : " + str(files) ^0
"files following the convention : " + str(following) + ", which is " + str(int(following * 100 / files)) + "%" ^0
"" ^0
"module        hops   files   following   rate   defects it would prevent/yr" ^0
for m in modules:
    "  " + m[0] + "   " + str(m[1]) + "      " + str(m[2]) + "      " + str(m[3]) + "          " + str(int(m[3] * 100 / m[2])) + "%    " + str(m[4]) ^0
"" ^0

# ---- the gradient ----

0 => prev_rate
1 => monotone
for m in modules:
    int(m[3] * 100 / m[2]) => rate
    if prev_rate > 0:
        if rate > prev_rate:
            0 => monotone
    rate => prev_rate
"compliance against distance" ^0
if monotone == 1:
    "  the rate falls at every hop, without exception" ^0
else:
    "  the rate does not fall monotonically" ^0
int(modules[0][3] * 100 / modules[0][2]) => near
int(modules[n - 1][3] * 100 / modules[n - 1][2]) => far
"  at 0 hops : " + str(near) + "%" ^0
"  at " + str(modules[n - 1][1]) + " hops : " + str(far) + "%" ^0
if near > far:
    "  a drop of " + str(near - far) + " points across " + str(modules[n - 1][1]) + " hops" ^0
"" ^0

# ---- where the convention would earn the most ----

0 => best
"" => best_name
for m in modules:
    if m[4] > best:
        m[4] => best
        m[0] => best_name
"the module where the convention prevents the most defects : " + best_name + ", " + str(best) + " a year" ^0
for m in modules:
    if m[0] == best_name:
        "  its compliance rate : " + str(int(m[3] * 100 / m[2])) + "%, at " + str(m[1]) + " hops" ^0
"" ^0

0 => close_prevented
0 => far_prevented
for m in modules:
    if m[1] <= 1:
        close_prevented + m[4] => close_prevented
    else:
        far_prevented + m[4] => far_prevented
"defects the convention would prevent, by distance" ^0
"  within 1 hop  : " + str(close_prevented) ^0
"  beyond 1 hop  : " + str(far_prevented) ^0
if far_prevented > close_prevented:
    "  most of the available benefit is where the compliance is lowest" ^0
"" ^0

# ---- what is actually being measured by "adoption" ----

"the adoption figure, as it is usually quoted" ^0
"  files following it : " + str(following) + " of " + str(files) + ", " + str(int(following * 100 / files)) + "%" ^0
"  what that number is a property of : how many files are near the author" ^0
0 => near_files
for m in modules:
    if m[1] <= 1:
        near_files + m[2] => near_files
"  files within 1 hop : " + str(near_files) + " of " + str(files) ^0
"  move the same convention into a codebase with a different shape and the" ^0
"  adoption figure moves without anybody's behaviour changing" ^0
"" ^0

# ---- what does not attenuate ----

"what a linter rule would do to the same gradient" ^0
"  hops it attenuates over : 0" ^0
"  what it cannot carry    : the reason, which is what lets a reader apply" ^0
"  the convention to a case the rule does not match" ^0
"  so the mechanical part travels and the judgement does not, and the" ^0
"  question is which of the two the convention mostly is" ^0
"" ^0

# ---- the control: a convention with no distance to travel ----
#
# In a codebase owned by one team, every file is at zero hops and the gradient
# has nothing to run along.

"control - the same convention in a single-team codebase" ^0
"  hops in play : 1 value, 0" ^0
"  compliance   : whatever the team decides, uniformly" ^0
"  the convention is then simply followed or not, and its adoption figure is" ^0
"  about the convention rather than about the org chart" ^0
"" ^0

"Following your own convention is the right way to demonstrate one, and the" ^0
"author's files are at 39 of 40. What travels is the rule; the reason stays" ^0
"where it was written, and compliance follows the reason." ^0

modules = [["core", 0, 40, 39, 8], ["adjacent", 1, 55, 44, 9], ["same org", 2, 70, 35, 12], ["other org", 3, 90, 18, 15], ["contractor", 4, 30, 3, 6]]
n = len(modules)
files = 0
following = 0
prevented = 0
for m in modules:
    files = files + m[2]
    following = following + m[3]
    prevented = prevented + m[4]
print("files in scope : " + str(files))
print("files following the convention : " + str(following) + ", which is " + str(int(following * 100 / files)) + "%")
print("")
print("module        hops   files   following   rate   defects it would prevent/yr")
for m in modules:
    print("  " + m[0] + "   " + str(m[1]) + "      " + str(m[2]) + "      " + str(m[3]) + "          " + str(int(m[3] * 100 / m[2])) + "%    " + str(m[4]))
print("")
prev_rate = 0
monotone = 1
for m in modules:
    rate = int(m[3] * 100 / m[2])
    if prev_rate > 0:
        if rate > prev_rate:
            monotone = 0
    prev_rate = rate
print("compliance against distance")
if monotone == 1:
    print("  the rate falls at every hop, without exception")
else:
    print("  the rate does not fall monotonically")
near = int(modules[0][3] * 100 / modules[0][2])
far = int(modules[n - 1][3] * 100 / modules[n - 1][2])
print("  at 0 hops : " + str(near) + "%")
print("  at " + str(modules[n - 1][1]) + " hops : " + str(far) + "%")
if near > far:
    print("  a drop of " + str(near - far) + " points across " + str(modules[n - 1][1]) + " hops")
print("")
best = 0
best_name = ""
for m in modules:
    if m[4] > best:
        best = m[4]
        best_name = m[0]
print("the module where the convention prevents the most defects : " + best_name + ", " + str(best) + " a year")
for m in modules:
    if m[0] == best_name:
        print("  its compliance rate : " + str(int(m[3] * 100 / m[2])) + "%, at " + str(m[1]) + " hops")
print("")
close_prevented = 0
far_prevented = 0
for m in modules:
    if m[1] <= 1:
        close_prevented = close_prevented + m[4]
    else:
        far_prevented = far_prevented + m[4]
print("defects the convention would prevent, by distance")
print("  within 1 hop  : " + str(close_prevented))
print("  beyond 1 hop  : " + str(far_prevented))
if far_prevented > close_prevented:
    print("  most of the available benefit is where the compliance is lowest")
print("")
print("the adoption figure, as it is usually quoted")
print("  files following it : " + str(following) + " of " + str(files) + ", " + str(int(following * 100 / files)) + "%")
print("  what that number is a property of : how many files are near the author")
near_files = 0
for m in modules:
    if m[1] <= 1:
        near_files = near_files + m[2]
print("  files within 1 hop : " + str(near_files) + " of " + str(files))
print("  move the same convention into a codebase with a different shape and the")
print("  adoption figure moves without anybody's behaviour changing")
print("")
print("what a linter rule would do to the same gradient")
print("  hops it attenuates over : 0")
print("  what it cannot carry    : the reason, which is what lets a reader apply")
print("  the convention to a case the rule does not match")
print("  so the mechanical part travels and the judgement does not, and the")
print("  question is which of the two the convention mostly is")
print("")
print("control - the same convention in a single-team codebase")
print("  hops in play : 1 value, 0")
print("  compliance   : whatever the team decides, uniformly")
print("  the convention is then simply followed or not, and its adoption figure is")
print("  about the convention rather than about the org chart")
print("")
print("Following your own convention is the right way to demonstrate one, and the")
print("author's files are at 39 of 40. What travels is the rule; the reason stays")
print("where it was written, and compliance follows the reason.")

files in scope : 285
files following the convention : 139, which is 48%

module        hops   files   following   rate   defects it would prevent/yr
  core   0      40      39          97%    8
  adjacent   1      55      44          80%    9
  same org   2      70      35          50%    12
  other org   3      90      18          20%    15
  contractor   4      30      3          10%    6

compliance against distance
  the rate falls at every hop, without exception
  at 0 hops : 97%
  at 4 hops : 10%
  a drop of 87 points across 4 hops

the module where the convention prevents the most defects : other org, 15 a year
  its compliance rate : 20%, at 3 hops

defects the convention would prevent, by distance
  within 1 hop  : 17
  beyond 1 hop  : 33
  most of the available benefit is where the compliance is lowest

the adoption figure, as it is usually quoted
  files following it : 139 of 285, 48%
  what that number is a property of : how many files are near the author
  files within 1 hop : 95 of 285
  move the same convention into a codebase with a different shape and the
  adoption figure moves without anybody's behaviour changing

what a linter rule would do to the same gradient
  hops it attenuates over : 0
  what it cannot carry    : the reason, which is what lets a reader apply
  the convention to a case the rule does not match
  so the mechanical part travels and the judgement does not, and the
  question is which of the two the convention mostly is

control - the same convention in a single-team codebase
  hops in play : 1 value, 0
  compliance   : whatever the team decides, uniformly
  the convention is then simply followed or not, and its adoption figure is
  about the convention rather than about the org chart

Following your own convention is the right way to demonstrate one, and the
author's files are at 39 of 40. What travels is the rule; the reason stays
where it was written, and compliance follows the reason.

Trace event types