OpEd: Regulations to Code

The Shadow Paradigm, a Guidance Doc

tl;dr: The paradigm of the code doesn't matter - the code should reflect/shadow the abstractions of the regulations it represents. There are other thoughts on guidance lower down, but that's the main idea we're trying out. Feel free to jam on this idea in your own way.

Other principles tl;dr

We should try to...

1. hit a balance between human and code readability. Err on the side of humans.
2. be suspicious of re-usability/abstractions that don't exist in the text. Regulations aren't like a regular code base. Not abstracting gives us flexibility. When one passage is changed while another isn't, we could get tangled in abstractions that don't make sense anymore.

Abstractions

Break out

Do: take our cue from the text.

If the regulations say 'If the individual is disabled as described in §271.2', then our code should look something like

let isDisabled = reg271_2(individual);
if (isDisabled) { ... }

Don't: give in to the lure of re-usability.

Use a coder's mindset about abstraction only where absolutely necessary. Two calculations that can be abstracted right now could turn into two unique calculations later. For example:

let reg1 = function () { return 5; };
let reg2 = function () { return 5; };

// Could be abstracted into
let return5 = function () { return 5; };

// Then reg2 turns into
let reg2 = function () { return 12; };

You've then got to track down where reg2's been used to fix it.

Arguments: There are other ways to do that which are more complex:

let return5 = function () { return 5; };
let reg1 = return5;
let reg2 = return5;

Pros: We can change reg2 when needed relatively harmlessly.

Cons: Considering how convoluted regulations are, it seems like this would quickly turn into a tangle, leaving behind unused or one-use functions. It also means that we have to interrupt what we're doing to hop to another part of the code to see what's going on. Some editors can help with that a bit, but it still adds cognitive load.

It still may be worth experimenting, though.

Break up

Do: break long passages apart into complete thoughts where needed.

Don't: try to account for every word or phrase. It seems to get unreadable pretty quickly.

Exceptions: There must be times when three words express so much that it really is necessary to break them out into code. We should be sparing with that if we can.

Names

Naming a thing gives you power over it! It also makes the code more readable in English, which is the language subject matter experts are familiar with. It also happens to be the language that most of us English-speaking coders are familiar with before we learn to code...

Abbreviations

Do: avoid abbreviations and name things as humanly/humanely as possible.

// do
let categoricallyEligible = reg273_2.j(household);
if (categoricallyEligible) {...}
// instead of
if (reg273_2.j(household)) {...}`

Don't: shorten names.

// do
let categoricallyEligible;
// instead of
let catElg;

Formatting

Do: use just one naming convention.

Don't: try to create 'categories' of naming, such as camelCase to identify money values and snake_case for time periods.

Don't: switch naming conventions mid-stream. If we use PascalCase, stick to that. If it's camelCase, that's the only case to use.

Meaningful

Do: come up with unique, descriptive, and meaningful names, not general or generic ones.

Example 1: for (let i...) probably should not happen. for (let memberNumber...) seems more readable.

Example 2: Something like startDate might end up getting us in trouble. householdWithChildrenStartDate might be more useful.

Don't: repeat names where possible.

Don't: go too crazy. It's a balancing act.

Where to Declare

Still under debate.

Option 1: Name everything at the top, that way we know what we'll be looking at.

Option 2: Name things at the top of each phrase/bit of continuous text that you break out. We'll know the pieces that are relevant to this specific part of the logic.

Option 3: Name things as they appear in the text/code. JIT (just in time) naming. It might line up most closely with the text.

User Testing

Do: work with users. This is a product as much as it's a code base. There are two groups of target users here - coders and regulation experts. We should iterate on abstractions and names together, checking in to see what makes sense to each other.

Don't: spend months working alone in a corner.

Working Examples

Yeah, that'll be the day. But seriously, we hope they're coming soon.