The Magic vs. Boilerplate Tradeoff

phil webb had an insightful tweet the other day.

what would you like to complain about?

[ ] too much magic
[ ] too much boilerplate

— phil webb (@phillip_webb) march 5, 2016

programming environments oscillate between boilerplate and magic. apis tend to start out with all the wires exposed. programming is tedious, but nothing is hidden. development is hard, but debugging is easy. see, for example, the hello-world program for win32 .

programmers get tired of this, and create levels of abstraction. boilerplate is reduced and development gets easier. and if the abstraction is done well, debugging doesn’t get harder, or not much harder. but this abstraction doesn’t go far enough. programmers feel like things should be easier still. that’s when magic comes in. magic differs from abstraction in that it not only hides details, it’s actively misleading. something appears to work one way, the desired way, but something quite different is going on. development gets easier, but debugging gets much harder. if the magic gets to be too much, developers look to start over with something more transparent, and the cycle begins again.

wizards, in the sense of code generators, are closely related to magic. whereas magic abuses language features to create illusions, wizards generate boilerplate code and become a sort of meta language.

webb’s comment about boilerplate vs magic came to mind this morning, not from looking at software, but at math. over time mathematicians discover better ways to organize material, turning some theorems into definitions and vice versa. this makes things easier in the long run, but creates a barrier to entry in the short term. math moves from boilerplate to magic, from relatively concrete and tedious to abstract but less obviously motivated. the definitions seem magical to the beginner because the applications have been delayed.

when i see this in an area i understand well, i think it’s clever. when i see it in an area i don’t know well, it feels like some sort of guild is trying to keep me out. i know that this isn’t the case—the machinery of mathematics is always created for practical reasons, not to intentionally intimidate anyone—but it can feel that way. it’s not so much that the motivation is deliberately hidden but that it is obscured. an unfortunate aspect of mathematics culture is that people are reluctant to discuss motivation in writing. it’s more likely to come out in conversation or in lectures.