2020-05-18 #programming / ferd.ca

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.

2020-01-08 #programming #react / overreacted.io

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.

2019-12-09 #programming

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.

2019-11-21 #programming

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.

2019-11-06 #programming #the-web / www.w3.org

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.

2019-11-04 #programming / spacecraft.ssl.umd.edu

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.

2019-10-29 #programming #oss

Writing open source software, and staying sane while at it

This was originally a lightning talk at Full Stack Europe 2019. You can watch the video on their YouTube channel.

In the 4.5 years I've been a developer at Spatie, over 200 packages have been built and released by our team. I've done quite some authoring and maintenance over the years, and I'd like to share 8 actionable tips on writing and maintaining open source software without going insane.

Read more

2018-12-06 #programming

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

2018-04-24 #programming #oss

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

2018-04-09 #programming #javascript #podcasts / spec.fm

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.

2018-02-15 #programming

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:

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

Read more

2017-08-21 #programming #spatie / guidelines.spatie.be

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.

2017-07-03 #programming / twitter.com

Fragmentation is fabulous

In a recent Twitter thread, Sebastian McKenzie (Yarn and Babel author) shared his thoughts on the current state of open source. This tweet stood out for me (and he later ironically dubbed it his "most thoughtleader tweet ever"):

Revel in fragmentation and duplication because without it there's stagnation and it stifles innovation.

When someone shares their latest pet project library, it's often met with responses like "What a waste of time, you can already do this with library X!".

There's no need for justification here. Maybe the author wants something that fully matches their use case instead of the 80% that library X does, maybe they want a different internal architecture. Maybe they have bigger future plans in mind, or most importantly, maybe they just want to experiment, learn, and have fun.

Read the entire thread on @sebmck's Twitter.

2016-03-09 #php #programming

Normalize your values on input

Dynamic languages allow us to pass anything as a parameter without requiring a specific type. In turn, this means we often need to handle some extra validation for the data that comes in to our objects.

This is a lightweight post on handling your incoming values effectively by normalizing them as soon as possible. It's a simple guideline worth keeping in mind which will help you keep your code easier to reason about.

Read more