Generalization and specialization: more of column A, a little less of column B

  1. Now, I attempt to write in the style of a tweetstorm. But about code. For my website. Not for tweets.
  2. For a long time, we have been embracing specialization. It’s taken for granted even more than capitalism. But maybe not as much as the sun rising in the morning
  3. From specialization comes modularization, inheritance, microservices, pizza teams, Conway’s Law, and lots of other things we sometimes consider as righteous as apple pie.
  4. Specialization comes at a cost though. Because a specialized entity is specific, it is useless out of context. It cannot exist except for the support of other specialized things.
  5. Interconnectedness is the unintended consequence of specialization. Little things depend on other things.
  6. Those dependencies may prove surprising, fragile, unstable, chaotic, or create a bottleneck.
  7. Specialization also requires some level of infrastructure to even get started. You can’t share code in a library until you have the infrastructure to import it at runtime (dynamic linking) or resolve the library’s dependencies (package managers).
  8. The expensive open secret of microservices and disposable infrastructure is that you need a high level of operational acumen to even consider starting down the road.
  9. You’re either going to buy this as a service, buy it as software you host, or build it yourself. Either way, you’re going to pay for this decision right in the budget.
  10. On the flip side is generalization. The grand vision of interchangeable cogs that can work any project.
  11. A year ago I would have thought this was as foolish as microservices. But the ecosystems and tooling are getting really good. And, JavaScript is getting good enough and continues to have the most amazing reach across platforms and devices.
  12. A year ago I would have told you generalization is the foolish dream of the capitalist who wants to drive down his costs by treating every person as a commodity. I suspect this exists in parts of our trade, but developers are generally rare enough that finding a good one is difficult enough, let alone a good one that knows your ecosystem and domain already.
  13. Generalization gives you a cushion when you need help a short handed team get something out the door. You can shift a generalist over to take care of the dozen detail things so the existing team can stay focused on the core, important things. Shifting a generalist over for a day doesn’t get you 8 developer hours, but it might get you 4 when you really need it.
  14. Generalization means more people can help each other. Anyone can grab anyone else and ask to pair, for a code review, for a sanity check, etc.
  15. When we speak of increasing our team’s bus number, we are talking about generalizing along some axis. Ecosystem generalists, domain knowledge generalists, operational generalists, etc.
  16. On balance, I still want to make myself a T-shaped person. But, I think the top of the T is fatter than people think. Or, it’s wider than it is tall, by a factor of one or two.
  17. Organizationally, I think we should choose what the tools and processes we use carefully so that we don’t end up where only one or two people do something. That’s creating fragility and overhead where it doesn’t yield any benefit.

The notes, October 04, 2017

I’m intrigued by folks having luck building virtualized development environments for localhost setups. It sounds like fun to work in this kind of workflow. I never want to do the legwork to make this work, though.

I did the preliminaries for this last year and ended up turning back from it. I understand Docker and virtualization superficially at best. I don’t want to impose it on teammates. It’s still too hard to search for Unix-y error messages and fix your development environment. Trying to figure out if your host Unix, Docker, or a virtualized Unix are the problem is not something I wanted to do to someone else.

Is Amazon Lightsail a move by AWS into the space occupied by Linode, Digital Ocean, etc.? Related to virtualized localhost setups: someone write me a thing to drop my dotfiles from macOS onto a Digital Ocean, AWS, etc. instance and do development from an iPad, keyboard, and SSH client.

Hammerspoon is a really cool to do all-the-things with your keyboard and some Lua. I use it to launch/switch to my most frequent dozen apps and some light Markdown helpers. But, something about it is correspondingly creepy. It can, theoretically, scoop up every keystroke. (Which probably every bit of open source I install via Homebrew could, to be honest) But maybe I could replace it with a clever bit of Alfred workflow and scripting. Catch a triggering keystroke and then give me a constrained list of apps to switch to. Yes, this is a very strange way to hit Command-Tab! I wonder how well a few custom Alfred workflows fit into a dotfiles repo.

Afternoon notes, October 03, 2017

Someone will always have a slicker Git workflow than you. For example,Auto-squashing Git Commits for clever rebasing.

The passage of time is weird, lately. Nonetheless, it’s surprising that the Dynamo white paper is ten years old. Ten years of NoSQL hype. Even from a naive yours truly.

I’ve been using the fish shell for about five months and it is pretty great. A shell with human affordances! It has very good guesses about what I want to do (completions) and what I want it to remember (history). You can configure it with a web interface or regular-old dotfiles. It doesn’t do anything bizarrely different from your typical Unix-style shell, namely bash, so there’s not much new to learn and when I SSH to a server, I don’t wonder what kind of weird contraption I’m interacting with. I haven’t bothered to learn its scripting language because I’ve decided no one should learn those anymore and they should use Ruby, Python, Go, etc. for that kind of thing.

Morning notes, October 03, 2017

I like Bluebottle’s coffee subscription service a lot. The web app is well done and having coffee magically appear in my mailbox means I have far fewer “awww heck we’re out of coffee until I go to a coffee shop” moments. However, I do occasionally mess up the timing, such as right now, and then I have a very first world problem.

Scheduling my time on social media and capping the total time spent, not unlike watching a regular TV show, is an idea with some appeal. It’s probably a good idea for moderating how much daily news one consumes, as well.

I was looking at WP-CLI so I could automate some housekeeping tasks on this blog. It’s pretty close to what I’d like to use, the ideal being something closer to t. I’m a little wary of installing a PHP tool though. It’s probably the language tribalism talking though. Seems pretty likely I’d save time using someone else’s PHP than figuring it out on my own.

The loungification of luxury cars

High-end luxury cars are starting to resemble first-class airport lounges and it’s bothering me.

The Porsche Panamera has a dang tray table. Just about every German luxury car has the option to put an LCD screen on the back of the front seats, for entertainment. Who puts $100k+ down on a car so that someone else can drive you around? The seats recline, have tablets to control their massage and scent-control functions. Of course they’re heated and ventilated.

I’m fine with cars as things that merely get you from point A to point B, and I’m fine with rich people buying extravagant cars, but I’m not okay with this airport lounge stuff. No one likes airports! They’re miserable! Stop designing things to resemble airports!

Categorizing and understanding magical code

Sometimes, programmers like to disparage “magical code”. They say magical code is causing their bugs, magical code is offensive to use, magical code is harder to understand, we should try to write “less magical” code.

“Wait, what’s magic?”, I hear you say. That’s what I’m here to talk about! (Warning: this post contains an above-average density of “air quotes”, ask your doctor if your heart is strong enough for “humorous quoting”.)

Magic is code I have yet to understand

It’s not inscrutable code. It’s not bad code. It doesn’t intentionally defy understanding, like an obfuscated code contest or code golfing.

I can start to understand why a big of code is frustratingly magical to me by categorizing it. (Hi, I’m Adam, I love categorizing things, it’s awful.)

“Mathemagical” code escapes my understanding due to its foundation in math and my lack of understanding therein. I recently read Purely Functional Data Structures, which is a great book, but the parts on proving e.g. worst-case cost for amortized operations on data structures are completely beyond my patience or confidence in math. Once Greek symbols enter the text, my brain kinda “nope!”s out.

“Metamagic” is hard to understand due to use of metaprogramming. Code that generates code inside code is a) really cool and b) a bit of a mind exploder at first. When it works, its glorious and not “magical”. When it falls short, it’s a mess of violated expectations and complaints about magic. PSA: don’t metaprogram when you can program.

“Sleight of hand” makes it harder for me to understand code because I don’t know where the control flow or logic goes. Combining inheritance and mixins when using Ruby is a good example of control flow sleight-of-hand. If a class extends Foo, includes Bar, and all three define a method do_the_thing, which one gets called (trick question: all of them, trick follow-up question: in what order!)? The Rails router is a good example of logical sleight-of-hand. If I’m wondering how root to: "some_controller/index" works and I have only the Rails sources on me, where would I start looking to find that logic? For the first few years of Rails, I’d dig around in various files before I found the trail to that answer.

“Multi-level magic schemes” is my new tongue-in-cheek way to explain a tool like tmux. It’s a wonderful tool for those of us who prefer to work in (several) shells all day. I’m terrified of when things go wrong with it, though. To multiplex several shells into one process while persisting that state across user sessions requires tmux to operate at the intersection of Unix shells, process trees, and redrawing interfaces to a terminal emulator. I understand the first two in isolation, but when you put it all together, my brain again “nope!”s out of trying to solve any problems that arise. Other multi-level magic schemes include object-relational mappers, game engines, operating system containers, and datacenter networking.

I can understand magic and so can you!

I’m writing this because I often see ineffective reactions to “magical” code. Namely, 1) identify code that is frustrating, 2) complain on Twitter or Slack, 3) there is no step 3. Getting frustrated is okay and normal! Contributing only negative energy to the situation is not.

Instead, once I find a thing frustrating, I try to step back and figure out what’s going on. How does this bit of code or tool work? Am I doing something that it recommends against or doesn’t expect? Can I get back on the “golden path” the code is built for? Can I find the code and understand what’s going on by reading it? Often some combination of these side quests puts me back on my way an out of frustration’s way.

Other times, I don’t have time for a side quest of understanding. If that’s the case, I make a mental note that “here be dragons” and try to work around it until I’m done with my main quest. Next time I come across that mental map and remember “oh, there were dragons here!”, I try to understand the situation a little better.

For example, I have a “barely tolerating” relationship with webpack. I’m glad it exists, it mostly works well, but I feel its human factors leave a lot to be desired. It took a few dives into how it works and how to configure it before I started to develop a mental model for what’s going on such that I didn’t feel like it was constantly burning me. I probably even complained about this in the confidence of friends, but for my own personal assurances, attached the caveat of “this is magical because it’s unfamiliar to me.”

Which brings me to my last caveat: all this advice works for me because I’ve been programming for quite a while. I have tons of knowledge, the kind anyone can read and the kind you have to win by experience, to draw upon. If you’re still in your first decade of programming, nearly everything will seem like magic. Worse, it’s hard to tell what’s useful magic, what’s virtuous magic, and what’s plain-old mediocre code. In that case: when you’re confronted with magic, consult me or your nearest Adam-like collaborator.

On Code Review:

Bias to small, digestible review requests. When possible, try to break down your large refactor into smaller, easier to reason about changes, which can be reviewed in sequence (or better still, orthogonally). When your review request gets bigger than about 400 lines of code, ask yourself if it can be compartmentalized. If everyone is efficient at reviewing code as it is published, there’s no advantage to batching small changes together, and there are distinct disadvantages. The most dangerous outcome of a large review request is that reviewers are unable to sustain focus over many lines, and the code isn’t reviewed well or at all.

This has made code review of big features way more plausible on my current team. Large work is organized into epic branches which have review branches which are individually reviewed. This makes the final merge and review way more tractable.

Your description should tell the story of your change. It should not be an automated list of commits. Instead, you should talk about why you’re making the change, what problem you’re solving, what code you changed, what classes you introduced, how you tested it. The description should tell the reviewers what specific pieces of the change they should take extra care in reviewing.

This is a good start for a style guide ala git commits!

Fewer changes are faster to deploy than fewer changes

Itamar Turner-Trauring, Incremental results: how to succeed at large software projects:

  • Faster feedback…
  • Less unnecessary features…
  • Less cancellation risk…
  • Less deployment risk…

👏 👏 👏 👏 👏  read the whole thing, Itamar’s tale is well told.

Consider: incremental approaches consist of taking a large scope and finding smaller, still-valuable scopes inside of it. Risk is 100% proportional to scope. Time-to-deliver grows as scope grows. Cancellation and deployment risk grow as time-to-deliver grows. It’s not quite math, but it is easy to demonstrate on a whiteboard. In case you happen to need to work with someone who wants large scope and low risk and low time-to-delivery.

TIL: divide by 10 with this one weird number

Running an application across two physical databases is not a straightforward thing. One of the relatively easier ways to do it involves assigning each database instance a shard number and then arranging for all your primary key IDs to end with that number. For example, shard 0 generates IDs like 1230, 40, 482340, shard 1 generates IDs like 1231, 41, 482341, and shard 2 generates IDs like 1232, 42, 482342, etc. all the way up to 9. If you want more than 10 database shards, it gets more involved.

My brain is wired oddly, so I came to wonder how you would quickly get the shard ID for an ID (e.g. shard 1 for 1231). This is really easy with decimal math; you just divide by 10. However, we run our databases on computers that can only do binary math, so its not actually simple.

But it turns out you can do it quite fast! There’s one weird number, expressed as `0x1999999A` hexadecimal, that is very close to multiplying by the fraction 1/10 (plus further binary math and register trickery). Thus you can do this in only a few instructions on Intel processors released in the past twenty years.

I’m really glad someone else figured this out.