Consistency

There are two bike stalls near my apartment. One is right in front of the door, the other around the corner. The one in front of the door is closest, so when I can, I store my bike there. However, most of the time that stall is full, and I need to go around the corner instead.

That's fine. Until a next morning–when I'm still in a daze because I'm not a morning person–I take the walk around the corner, only to realise my bike was actually in front of the door. The day before was one of those lucky days I could store my bike in front of the door.

I quit using the front stall. The less choices I have to make, the more room I have for important things.

Read more

Unlearning

As developers, we often talk about the importance of learning. Learning is so important to us, that it's worth persuing ways to improve the way we learn.

One way to become a better learner is to master the reverse: unlearning. Not the ability to completely forget, but the ability to set something aside for a brief moment.

When we learn a new language, framework, or tool, it's hard not to dismiss new ideas based on our existing opinions. It's the mental baggage we carry along all day.

What we've established as antipatterns in tool X's, might be shiny tool Y's bread & butter. That doesn't mean we should dismiss tool Y. Ideas on their own are rarely good or bad, they need to be evaluated in a certain context.

Read more

Builders and architects

My colleague Brent wrote a food-for-thought post about two different kinds of programmers: builders & architects.

The first ones, the builders, are the programmers who get things done. […] On the other hand there are architects. They are concerned about sturdy and structurally sound code. […]

These two types of programmers seem like opposites. They themselves look at the other group and often think exactly that. They have a different way of handling the same problems. The other group's solutions are so different, they can't possibly be right, or so it seems.

Builders often find architects too rigid and conservative. They follow the rules for the sake of following them, without any practical benefit. Architects in turn, think of builders as careless, too focused on results, instead of thinking about long-term maintainability.

Different programmers aside, "build vs. architect" is the eternal internal conflict when I want to make decisions. Striking a balance between "getting things done" and "getting things right" is tough.

Read the entire, beautifully illustrated post on stitcher.io.

Complexity has to live somewhere

By Fred Hebert:

  • if you make the build tool simple, it won't handle all the weird edge cases that exist out there
  • if you want to handle the weird edge cases, you need to deviate from whatever norm you wanted to establish
  • if you want ease of use for common defaults, the rules for common defaults must be shared between the tool and the users, who shape their systems to fit the tool's expectations
  • if you allow configuration or scripting, you give the users a way to specify the rules that must be shared, so the tool fits their systems
  • if you want to keep the tool simple, you have to force your users to only play within the parameters that fit this simplicity
  • if your users' use cases don't map well to your simplicity, they will build shims around your tool to attain their objectives

The endless loop of software development. Complexity is why what starts out as "a lightweight alternative to X" often ends up as bloated as X. Greenfield projects allow you to not care about the edge cases for a while, but complexity always catches up.

Read the full article on ferd.ca.

What are the React team principles?

Dan Abramov shared a short post on some key principles the React team sticks to. Some solid general advice here, it's not explicitly related to React.

Absorb the Complexity

Making React internals simple is not a goal. We are willing to make React internals complex if that complexity lets product developers keep their code easier to understand and modify.

Hacks, Then Idioms

We need to allow hacks using escape hatches, and observe which hacks people put in practice. Our job is to eventually provide an idiomatic solution for hacks that exist in the name of better user experience. Sometimes, a solution might take years. We prefer a flexible hack to entrenching a poor idiom.

These two stood out because they're the opposite of how I generally need to think when building applications (although they make perfect sense in the context of something like a lower level framework). Either way, lots of food for thought in here.

Read all principles on overreacted.io.

Strawberry jelly

Have you ever made your own strawberry jelly? The recipe is straightforward: toss together 1 cup of strawberries (fresh or frozen), 1 cup of sugar, and 1 tablespoon of pectin (to thicken). Bring to a boil and let it cool.

Congratulations, you've made your own jelly! It also tastes 10x better than store-bought jars. You can tweak ratios and swap ingredients to your own delight, and it takes about 5 minutes to make.

Before we started making our own jelly at home, the thought never really occurred to me. I simply had the habit of buying jelly at the grocery store. Not knowing how to make jelly made me assume it was either diffucult or required a time consuming process. As it turns out, neither are true.

While I'd love to have a cooking blog at some point of my life, this one's still about programming. Where am I heading here?

External libraries are like strawberry jelly.

Before you npm install strawberry-jelly, consider making your own. Having an entire ecosystem of packages at your fingertips is amazing, but dependencies come at a cost. The cost of not fully understanding or owning the code. The cost of a package being a general solution: it might be incomplete or too complete, adding unnecessary weight.

Making jelly is a worthy tradeoff because it's fast and easy to make, and substantially better than the alternative.

I'm not asking anyone to stop installing dependencies altogether, but to think twice before adding an external helpers or toolboxes. Don't install dependencies when they're an easy solution, install them when they're a better solution.

Shop-built jigs

Back in the summer we were working on a new version of our package documentation site at Spatie.

Back then, all docs for all packages were stored as markdown files in a single docs.spatie.be repository. This made the website easy to maintain, but separating the docs from their code added unnecessary friction for contributors to also contribute to our docs when sending a PR.

We wanted to change things up and move the markdown files to their respective package repositories. This meant we had to come up with a way to aggregate files from multiple git repositories and serve them from a single website.

We ended up with an unsexy, procedural, 38 line node script to fetch all markdown files and copy them to a local folder. Then a simple static site generator does its thing and turn those markdown files into the website they were meant to become.

We could have built a custom web app, and the code would've been cleaner and have a pure architecture. Instead, we ended up with a script that fits on a 13" screen and a zero-config static site generator.

Don't be afraid to choose a crude, simple, shop-built jig over a complex solution just for the sake of purity.

The rule of least power

During his lightning talk at Full Stack EU, Bram Van Damme mentioned the rule of least power.

The rule of least power was described in an essay by Tim Berners-Lee back in 2006.

When designing computer systems, one is often faced with a choice between using a more or less powerful language for publishing information, for expressing constraints, or for solving some problem. This finding explores tradeoffs relating the choice of language to reusability of information. The "Rule of Least Power" suggests choosing the least powerful language suitable for a given purpose.

This is a useful principle to follow for the web because less powerful languages fail better.

Forgot a closing tag in HTML? There's a fair chance the browser will just fix it for you.

Did you write an invalid or unsupported CSS rule? The browser will ignore the statement and parse the rest as intended.

Got a syntax error in your JavaScript app? Prepare to watch the world burn.

Read the full essay on w3.org.

Akin's laws of spacecraft design

Back in 2003 when I was still in elementary school, Dave Akins wrote a list of laws to abide when building a spacecraft. I'm not planning to build one of those any time soon, but there seem to be many similarities with web development. A few examples:

  • Engineering is done with numbers. Analysis without numbers is only an opinion
  • Design is based on requirements. There’s no justification for designing something one bit “better” than the requirements dictate
  • Don’t do nuthin’ dumb

Here's a good one te keep next to your desk, and consider yourself lucky next time you ship a bug to production.

  • Space is a completely unforgiving environment. If you screw up the engineering, somebody dies

Read all 44 laws at their home on spacecraft.ssl.umd.edu.

Readability is relative

When I write a library that's going to be used by others, I strive for a gentle learning curve. When someone reads code that uses my library, I want them to understand what's happening without reading a bunch of documentation first. I tend to keep my API's as explicit as possible, and try to stay away from odd or foreign notations.

My colleague Brent is writing a library to deal with date & time periods in PHP. There was a discussion whether a period's boundaries should be included in the range or not.

Read more

A good issue

Maintaining a number of open source projects comes with a number of issues. Reporting a good issue will result in a more engaged approach from project maintainers. Don't forget: there's a human behind every project.

Read more

Design Details: Incremental Correctness with Guillermo Rauch

In a recent Design Details podcast, Guillermo Rauch (@rauchg) shares his thoughts on the web, design, the value of code, type systems, cryptocurrencies and much much more.

I have a lot of respect for Guillermo's philosophies, and what he's building with Zeit. An early quote from the interview (paraphrased):

I've always had this passion for the hyperlink. My whole thesis is everything that has not yet been hyperlinked, will be hyperlinked. If we step back and take that thesis a little further—you look at GitHub and they but a hyperlink on everything. They put a hyperlink on every per-character diff of your codebase. Every line of code. Every changeset. Everything.

Listen to the full podcast on Spec.fm.

A pair of helping hands when naming things

One of the hardest (and sometimes frustrating) tasks in a programmer's day-to-day workload is naming things. When I have a hard time finding that perfect word, I generally wind up in one of two situations:

  • I have a plausible name in mind, but I'm not entirely satisfied with it
  • I have no idea what I could possibly name it

Luckily, there are tools out there that can be of help.

Read more

Introducing our company guidelines site

We just open sourced our company guidelines site! We previously kept the contents in a private wiki on GitHub, but I'm glad we finally put the time in giving the contents a real home.

Like our docs site, the content is stored in markdown files, which can directly be edited on GitHub. The site deploys whenever something's pushed to the master branch.

As for why we decided to open source it all...

This site contains a set of guidelines we use to bring our projects to a good end. We decided to document our workflow because consistency is one of the most valuable traits of maintainable software.

The contents of this site exist for ourselves—more importantly, our future selves—and for giving future collegues a reference to our way of doing things and their quirks. The guidelines cover workflow, code style, and other little things we consider worth documenting.

The guidelines are available on guidelines.spatie.be.