Reflections on Expression Rules

Just like gram­mar it­self, Harper is rule-based. These rules can be writ­ten by hu­man or ma­chine, and usu­ally take the form of a “phrase cor­rec­tion” or an ex­pres­sion rule. You can read more about both in my guide.

In essence, an ex­pres­sion rule is a small, de­clar­a­tive pro­gram that seeks out spe­cific cases Harper can be cer­tain are gram­mat­i­cally in­cor­rect. For ex­am­ple, we know re­dun­dant modal verbs are al­ways wrong:

We could give it try attempt.

What’s Great About Expression Rules

As the main­tainer of the pro­ject, I need to read through a de­cent num­ber of pull re­quests each week. De­pend­ing on their com­plex­ity, this can be time con­sum­ing. Be­cause ex­pres­sions are al­most al­ways writ­ten with the same five prim­i­tives, they make re­views way faster. For many rules, I only need a quick skim of the code and to con­firm they don’t cre­ate false-pos­i­tives.

In ad­di­tion to ty­pos, the prim­i­tives un­der­ly­ing ex­pres­sion rules were de­signed to check agree­ment and word-or­der­ing er­rors. To that end, there are a num­ber of as­sump­tions baked in. This makes some kinds of rules harder to write, but also makes all ex­pres­sion rules ex­ceed­ingly easy to mem­o­ize.

What’s Not-So-Great About Expression Rules

As I said be­fore, ex­pres­sion rules were de­signed for a cer­tain kind of er­ror. There are many gram­mat­i­cal or lay­out rules which hard dif­fi­cult or down­right im­pos­si­ble to de­fine with an ex­pres­sion.

This nor­mally is­n’t prob­lem, since we can go about them in other ways. On mul­ti­ple oc­ca­sions, how­ever, I’ve seen po­ten­tial con­trib­u­tors get frus­trated at a per­ceived lack of flex­i­bil­ity. We did­n’t make it clear enough that there were so­lu­tions other than ex­pres­sions.

How Can We Improve?

Applying Amdahl’s law, I think the most ef­fec­tive so­lu­tion is to im­prove our doc­u­men­ta­tion, as I have been for the last week or so.

Beyond that, re­mov­ing the need for boil­er­plate code and other causes of men­tal over­head (like reg­is­ter­ing our rules and wait­ing for a slow com­pi­la­tion process) might lower the per­ceived dif­fi­culty of writ­ing new rules.