Effortless SDKs

The Data Problem

So you want to build a Spotify app? Or maybe take payments using the Stripe API? Or maybe you only want to talk with your back end. All of these require writing HTTP requests, writing encoders and decoders. It’s a pain. If you’re looking to use a large API like Square’s this can mean tens or hundreds of endpoints with a variety of types to pass in. Do you really want to write up all of that wiring? I don’t! What are we to do?

An Answer

Why not generate it all! Very handily each of these services, and many more, provide an Open API Spec that defines all of their endpoints and how you use them. Quick aside, this spec used to be known as Swagger so if you ever see that name you’re likely looking at an older version. Now that we have a structured way of talking to a large variety of APIs, how do we use it?

This is why I’ve written the Elm package wolfadex/elm-open-api. This package allows us to parse these specs and use them inside any Elm app. That’s step one down, and we’ll come back to it more later, but how does this help us write encoders, decoders, and make requests? That’s where my Node package comes in, elm-open-api! This package is a CLI tool for taking an Open API Spec (OAS) and transforming it into an Elm module. It generates your encoders, decoders, and the HTTP requests (both Cmds and Tasks) for every endpoint and data structure. Now instead of spending your time wiring it all up, you can spend if focusing on building your app. For an example, I’ve forked the Elm Land RealWorld app to use elm-open-api.

Beyond HTTP

Is that all? Far from it. An OAS is useful for far more than making requests. It just so happens that it also contains documentation information. Now we can parse an OAS and generate docs, maybe even using elm-pages to statically render (note: this is how Square generates their docs).

Surely that’s it? Not quite! There’s one more project I have in the works as a follow-up. Internally, OAS uses JSON Schema to define the request bodies, responses, and query params. Additionally there’s a small schema, UI Schema, that can be combined with JSON Schema to define forms meaning… form generation! This work is still a little ways off but it’s perfectly practical.

What’s Next

This is a lot to think about, and to be honest there’s a lot of work still to do, but I’m happy to have an initial version out as this has been in the works for 2 years! There’s still a lot of improvements to be made to the OAS Elm package like supporting older versions and handling of custom fields. There’s also work to be done on the Node package to generate better error handling. I have some crazier ideas involving OAS and codegen as well, though I’m saving those for another day 😉

Bring Your Own DOM – Part 2 – TUIs

Mise en place for making pasta, from catceeq.

In part 1 we talked about some basic setup for building portals. That was cool and useful and … there’s not much to do with it. What if we want to go further? What if we wanted to write Elm to build textual user interfaces (TUIs), something like Ink or Bubble Tea.

What is a DOM?

Most people would say “That’s impossible! Elm is only for web apps.” Well, that’s kind of true. Elm is designed for writing to a DOM, and browsers use a DOM. Let’s look at MDN’s definition

The DOM represents a document with a logical tree. Each branch of the tree ends in a node, and each node contains objects. DOM methods allow programmatic access to the tree. With them, you can change the document’s structure, style, or content.

Nodes can also have event handlers attached to them. Once an event is triggered, the event handlers get executed.

https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model

I’ve chosen to add emphasis to the key points here: the DOM is a tree, which we can change, and add event listeners too. There’s nothing here that says it can only exist in a browser, and back in part 1 we figured out a way to setup a faux node that defines the 7 or so DOM methods that Elm uses. Could we write other kinds of faux nodes?

The ingredients of our DOM

For those that like to jump ahead, a link to the repo I’ve been playing around in.

For those that like to be guided, lets begin. For our DOM we’ll need a few ingredients. First our portal web component from part 1 with all of it’s basics like childNodes and setAttribute. Next we need a “document”. Finally we need some helpers to tie it all together.

Starting with the simplest ingredient first, the “document”. Elm expects the context its created in to have access to context.document. This document needs 2 functions and 2 properties. The first function is createTextNode, which does as it says by creating a new text node in its tree. The second is createElement, which creates a non-text node in its tree. The properties are then .body which returns the root or “body” node of the tree and .title which is used for getting & setting the title of your document.

Now that we have a document, we need to work with the nodes, aka elements, aka the tree. This is where that portal comes in. We can largely copy the skeleton of it and then update the body of each function to match our new goal. Before we were forwarding messages to another browser DOM node, but now we’re responsible for creating, updating, viewing, and destroying our own nodes!

Gluing it all together

“But wait!” you say, “How can we glue it all together if we don’t have nodes yet?” We’ll get to that, saving the best hardest part for last. The easiest way of gluing it all together is to define our own Elm Program. In my package this is done with Ink.program, which looks strikingly similar to Browser.document only instead of body : List (Html msg) it expects body : Ink msg. Doing this allows us to control what view code we allow to be written and what it means in the context of an Ink app.

So what then is Ink msg and where do I buy one? Well similar to Html.text and Html.div I provided Ink.text and Ink.column. Instead of div : List (Html.Attribute msg) -> List (Html msg) -> Html msg you get column : List (Ink.Style msg) -> List (Ink msg) -> Ink msg. Nearly identical, only scoped to our new context.

Finally this is all tied together with Html.node "elm-ink-node-name". Which leaves us with one final question.

What is a Node!?

The basics of a node can be straight forward. A text node only needs to print a string to the terminal which could be process.stdout.write("your text"). They don’t have children, or styles, or events so we’re done!

That’s boring though. We want color! We want interaction! We want layout!

This is where things get complicated, and where I’m still struggling to build something of high enough quality that I feel like publishing this as a package. It’s why there aren’t docs. It’s why I’ve taken so long to even write this blog post.

I have an example in the repo of wrapping the Node package blessed, which is a JS package for building TUIs, but it never felt quite right. Layout felt wrong and the docs were difficult to work through. I have another example using Facebook’s Yoga. This works well for layout, if you can manage to stumble your way through the (lack of) docs, but it makes events more complicated. It’s also difficult because it doesn’t account for borders in a way that’s easy to work with.

Where to go from here?

I do plan on continuing this work and I think it’ll be useful. It’s the reason I wrote wolfadex/elm-ansi, and I think the community could benefit from this work. Whether you’re writing a script using elm-pages or if we wanted to move tooling like elm-review’s CLI or Elm Land’s CLI to Elm, this would let us do so with ease. If others are interested, I’m open to PRs and other input. I also hope that someone out there will feel inspired to write their own DOM for another platform. Maybe next year we’ll get elm-mobile or elm-iot or elm-arduino!

I also realize that this may be a little open-ended. If you have questions please feel free to reach our on Slack, Discord, Mastodon, or wherever you can find me as wolfadex and I’ll do what I can do answer your questions.

Elm Camp 🏕️

First and foremost it was so nice to be able to meet so many people in person that I’ve known online for years. The most important part of Elm for me is the community and being able to experience it in person was truly special.

---

Venue

The venue was also incredible. I’ve never stayed anywhere quite like it before, and don’t imagine I will again anytime soon.

The grounds of the place were incredibly well maintained too, with fire pits, picnic tables, a robot lawn mower, and more.

I especially loved the forested areas as they reminded of where I grew up.

---

Sessions

There were many sessions and even more chats happening between and during. There were almost always 2 or more I wanted to be a part of. The ones I was able to attend were: Next 5 years for Elm, Elm in Business, Reflecting on the Last Few Years, Games with Elm (I hosted/led this conversation), elm-dev, Elm for Beautiful Art & Music, Getting an Elm Certification, Funding Elm, Let’s Play Games, Internationalizing Elm, Forms, and The Making of Elm Camp. I’ll try and reflect, in no particular order, on what I remember, as I know there was a lot I’ve forgotten.

Games with Elm
I hosted the Games with Elm session, partly because there was a fair amount of interest in having one and because I’ve spent the past 2 years slowly working on a game engine. I don’t have a lot to show at the moment as I’m in the middle of a very large refactor, but I think I’m getting close to something minimal. I’m also in the midst of moving houses so that may delay my refactor a tad.

elm-dev
This for me wasn’t particularly enlightening because I’ve already contributed a tad to the project. I am very excited to see it released though, and it was fun to hear the conversation.

Internationalizing Elm
I’m quite interested in the future of this work. It’s slightly inspired by Felienne Hermans’ Hedy programming language, which I’m a huge fan of. I’m also excited because I feel like it aligns so well with the ideals of Elm.

Elm for Beautiful Art & Music
This was my favorite of the sessions. I’d never seen Casper’s work before, and I really love personal art. I also really like art that’s ephemeral, and his work kinda hit all those sweet spots.

Getting an Elm Certification
This was an interesting one for me. I don’t have any certifications of any sort, I don’t even have any degrees beyond my high school diploma. I also realize that companies like to have these sorts of things. I know I’ve lost job opportunities because I don’t have a degree, despite having all of the necessary skills and experience. If providing people certificates of some sort could help them to get a job then I’m all for it.

Reflecting on the Last Few Years
This was the only one of the non-Elm and non-technical sessions I attended. It was, as the title says, about reflecting on the past few years. I won’t share what anyone else shared with me. I won’t share a lot about my time beyond it being challenging in ways far beyond covid.

The Making of Elm Camp
This session felt relatively straight forward but it was still fun to hear from Katja and Mario. It also has me hopeful for future Elm Camps all around the world.

Elm in Business
This is one of the ones I remember the least at this time. Was happy to participate though as I enjoy using Elm for work and find it a highly appropriate tool for building things with code.

Forms
This was all about building forms in Elm. I once spent a year building highly complex forms in React and don’t want to repeat the coding experience, the team was great though! It definitely has shaped my view on forms in any language or framework being more of a complex and custom creation than most people appreciate.

Let’s Play Games
We spent a half-hour playing games that we and others had created. It was a lot of fun! By far I think the biggest hit of the session was Unblank by Ryan Haskell-Glatz.

Funding Elm
Not entirely sure what to say about this session. I think my 1 take away is that it’s challenging to have a world full of people who buy yachts, people who never want a yacht, and a variety of gray in between.

Next 5 years for Elm
One of the requirements for building a tall building is having a solid foundation. The taller the building, the more solid of a foundation necessary. Well I love mega structures. Were I a structural engineer, I’d want to be building the longest bridges and the tallest towers. But I’m a software engineer. Which means I want to write software that is the lowest maintenance burden, the easiest to refactor, and feels invisible to the user. If today I’m building 50 story skyscrapers in Elm with ease, in 5 years I expect to be building 500 space scrapers with ease.

---

Heading Home

As much as I loved Elm Camp, all things must end. I didn’t head home right away though. Bekah and I ended up spending an extra few days enjoying Denmark in all its beauty. But that’s another story.

Bring Your Own DOM – Part 1 – Portals

A banana traveling through a portal, from ThomasWolter

I’ve realized I’m not great at lengthy posts. Neither completing them, nor finding the right words.

Another thing I’ve come to realize over the past year is Virtual DOMs (vdom) have a sort of beauty in their simplicity. They generally have 2 basic actions: insert and remove. Combine this with the malleability of JavaScript and beautifully, simple magic can happen.

Portals

The code is here for those that like to jump to the end. Linking it in a gist because over the past year we’ve made 1 or 2 tiny adjustments and I’d rather give you the current working code than something outdated.

How do they work?

window.customElements.define("elm-portal", class extends HTMLElement {
  ...
}

We first define a custom element. Naming is hard, so why not follow the common naming of <domain>-portal.

constructor() {
  super();
  this._targetNode = document.createElement("div");
}

Our portal needs a target location to end up at, so we define one.

connectedCallback() {
  const selector = this.getAttribute("data-target-selector");
  const destination = document.querySelector(selector);
  destination.appendChild(this._targetNode);
}

When our element is added to the DOM, we want to make sure our target location is present. We declare how we’re going to find it with const selector = this.getAttribute("data-target-selector"), then reach out and grab it with const destination = document.querySelector(selector);, and finally place our target at the destination with destination.appendChild(this._targetNode);

disconnectedCallback() {
  const selector = this.getAttribute("data-target-selector");
  const destination = document.querySelector(selector);
  destination.removeChild(this._targetNode);
}

We don’t want to forget to remove our destination when our portal is removed, otherwise we could end up with wild clones of our self!

---

So far this has all been basic JavaScript custom element code. Now for the Elm specific code!

get childNodes() {
  return this._targetNode.childNodes;
}

Sometimes the Elm vdom needs to retrieve the list of child nodes, so we forward on that request.

replaceData(...args) {
  return this._targetNode.replaceData(...args);
}

Other times the Elm vdom asks to replace some data, so we forward on that request.

removeChild(...args) {
  return this._targetNode.removeChild(...args);
}

Elm’s vdom definitely needs to be able to remove a child, so we forward on that request. Noticing a pattern here?

insertBefore(...args) {
  return this._targetNode.insertBefore(...args);
}

Sometimes it’s asks to insert something before our portal, so we forward on that request too.

appendChild(...args) {
  // To cooperate with the Elm runtime
  requestAnimationFrame(() => {
    return this._targetNode.appendChild(...args);
  });
}

Finally Elm’s vdom will ask to append a child to the portal. So, as usual, we forward on that request.

That’s it?

Yep, that’s it. All that’s needed to have portals in Elm is to forward these 4 functions calls and 1 property request. Adding this to your project will allow you to define an element in 1 location and have it appear in another.

Do I need this?

Hopefully not for long. Today it’s very helpful for building custom dropdowns, tooltips, and anything else that needs to be “on top” no matter where it’s defined in your view code. Thankfully there’s a proposal for a popover API that would allow all of this functionality, and more, without the need for custom elements!

So then, why share this? Well this is just the tip of the ice berg. In part 2 we’ll see how this train of thought can take us far beyond the browser.

I also need to give credit to Ryan Haskell-Glatz for pairing with me on this for many hours. A good chunk of my first week at Vendr was figuring this out and it’s made our code a lot more clean and easy to use.

Ducks

At Vendr we’re a remote first company. Most of my coworkers, even my team, I’ve never met in-person. And yet I feel very connected to not only the people on my team but people on other teams, in other departments! How?

Rubber Ducks

We keep in touch through rubber ducks! No, not actual rubber ducks but our own, personal rubber duck channels in Slack.

What does a Rubber Duck look like?

For us, a rubber duck channel looks like #rd-<name>, or more concretely mine is #rd-wolfgang. For those not familiar with Slack what I’m describing is a space within Slack that is open for anyone else in our company to jump in & out of, but is primarily my space.

How do we use these Ducks?

Every day I message post new messages into my RD of what I’m working on. What TV I’m watching. What games I’m playing. Cool things I found. It should be mostly work related, but it’s cool to talk about non-work stuff as well! I like to think about it like the desk I’d have at a physical office. In an office people can walk by your desk and see what you’re working on or overhear what you’re chatting about. Same applies here! You stop on by your Ryan’s RD and see them post about the latest season of Love is Blind, and guess what I’m also watching it too. Let’s chat! As we’re chatting, Laney checks in to Ryan’s RD and also happens to be watching Love is Blind so they join in on the conversation.

Sounds noisy & distracting!

There are some days where it is, but it’s easy to mute Slack or even just a particularly noise RD, like putting on headphones in an office. However this approach to communicating has also had some amazing benefits.

Numerous times I’ve passed through someone’s RD and see that they’re stuck. Just so happens that I saw another coworker solve the same problem 2 days ago. I can quickly give them a link to the other person’s solution and now they’re unstuck!

Other times I’ll be posting about the feature I’m working on and coworker will hop in to my RD and point out that we already have someone else working on this. Turns out our PM’s forgot to mention this to each other and we almost did duplicate work.

But wait, there’s more!

Posting about being stuck, and then how you got unstuck is also super helpful because these RD’s are public (within the company) and it’s very easy search the whole Slack for what you’re stuck on. There’s a pretty good chance that a coworker has already figured out the solution and you can just copy their fix! This has saved me hours of being stuck.

Before RDs I’d often find myself spending hours being stuck and waiting for any coworker to come help me out. Now I typically spend no more than 5-10 min waiting for someone to help me, or even just 1-2 min finding a solution by searching. Sometimes the person helping you to get unstuck is actually you. You hit an error today that you also hit a month ago, now you’re helping yourself and others!

There’s also a common theme at work of “building in public” and “support”. Everyone I talk to at work about RDs mentions feeling a sense of support, both for their team and the company. Before RDs many of us felt closed off to what the company is working on & towards. Now, because we’re talking in public, we’re also building in public. Have a question about a feature and not sure who to talk to? Just search Slack and you’re bound to find someone else, usually multiple people, talking about building it.

How can I get in on this Duck action?

When I joined Vendr, RDs were already the standard and mandatory for every new-hire. So I can’t talk from experience of how to promote these within your company. My suggestion would be to talk about it with your manager, and your team, and share some tweets and blog posts about people who do use this practice.

---

I know my coworkers could add another 10 paragraphs here about how they benefit from Rubber Duck channels, and I’d love to hear their thoughts in public 😉. For me this feels like a good starting place. If you’d like to read or hear some of their thoughts, checkout Duncan Malashock’s Tweet thread or this interview with Aaron White on Engineering Excellence.

When you can’t delete any more

I didn’t realize it when I set out, but I think I’ve started to figure out what role I play on my teams. I enjoy removing the unnecessary. I feel a sense of satisfaction when the thing before me is in its minimalist form. Now before you bail thinking that I’m going to try selling you on removing things from your life or that I’m a fanatical minimalist here to preach , I’m not. Minimalism isn’t about reducing things till there’s nothing left, and despite Sol LeWitt being one of my favorite artists I don’t think everyone should be living in IKEA styled homes.

Sol LeWitt, Cube

So if I don’t mean this stark white, barrenness when I say minimalist what do I mean? I’m talking about removing the things that, as Marie Kondo might say, don’t spark joy. Or being a software developer this to me means removing the features which don’t bring joy to my users, nor to my team. The software I build should bring joy to your life even if the task it’s used for is boring, or worse brings displeasure (like doing your taxes).

How to Bring Joy to Users?

Window’s Solitaire win screen

No one wants to fill out forms, but as developers we can make that experience better. Just this past week at work we removed optional fields for many of our forms. These fields only distracted from what the user was trying to do. We de-cluttered the process so the user can get their job done and move on with what they truly care about.

We also made our forms consistent across all of our app because no one wants to have to re-learn how to fill out a form just because they went to a different page. The user isn’t using our app because they want more work, they’re using it to give themselves more time to focus on their business and the things that bring them joy.

We didn’t only remove though, we also added. We added new paths to for the user to get to their destination. We added color, a bit of flair, to brighten their day. We added clarity around names to make it easier to distinguish intent. We created just as much if not more than we removed.

How to Bring Joy to Software Creators?

person frustrated by their computer, by @olly

This is where it all really comes together for me. Bringing joy to the customer is commonplace everywhere I’ve worked. Making the customer’s life easier means they want to come back, and if they want to come back then they’ll continue to pay you for your services. It’s how we accomplish this that often brings dissatisfaction for me and other developers.

Take a look across the landscape of developer tools and you’ll see an endless supply of tools that make it easier to add more code, more quickly. A million and one banners and quips about how Popular Framework makes it easy to add more, and do so faster than ever before! There’s always another blog post on how to add another service to your tech stack. How to add, add, add! It’s all written with a blind disregard for the developer who’s written their app, has their users, and now needs to change a feature. What about the developer who inherits 10k, 100k, 1M lines of code and needs to remove a feature? What about the developer who’s trying to pivot their startup from who they thought their customer was to who their customer actually is?

What about me?

Finding Joy

Sol LeWitt, Splocth #3

This was me until a couple years ago. Every project I came into had endless features for the user, and no easy way to remove them. It didn’t bring the user joy, and it brought me even less. We couldn’t remove fields because no one could figure out how they all worked together, so instead we’d hide it from the user (but not the developer) or worse yet rewrite it all. The company would spend millions of dollars throwing away the working product to create it brand new, but “better”. I knew there was a better way but it’s hard to convince teams who’ve become numb to this normalcy.

Last year I finally got a chance to be a part of not only a team but a company that embraces both refactoring and deleting code. Where refactoring 1/2M lines of code is normal instead of a complete rewrite. Since joining, I’ve both created and removed features. Giving the users the features they need and removing those that only got in their way. In the last 3 months alone I’ve been able to delete over 20k lines of code from our app. Removing code the user never sees, and only distracted my coworkers from accomplishing their goals.

Make Deleting Code Easy

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.

Antoine de Saint-Exupéry, Airman’s Odyssey

Cool, so I found a company that makes it easy, but what about everyone else? Well if you’re like me and you liking deleting code then lets make it easier for you. The simplest route may be to join me at Vendr, building an app that brings others joy by reducing the work they have to do managing vendors. But that’s not for everyone. Changing jobs can be challenging, and you might like your current employer.

The next route may be using our tech stack. The tools that have allowed me to delete so much code with ease is actually quite small, it’s just Elm and elm-review¹, nothing more. While many languages attempt to remove unused code, Elm takes the opposite approach and only includes the code that is actually used. Live code inclusion. This means you’re never² including unused code. While Elm doesn’t include the unused code in your build it still exists in your project, that’s where elm-review comes in. This is also the magic that allows me to delete so much code. With just 6 elm-review rules I can go about my day and let my linter remove all of the unused code from my project!

Again, this isn’t for everyone. Maybe your team or employer doesn’t want you using Elm. Maybe you don’t want to or even can’t write Elm! Then I suggest reaching out to your communities language and linter authors and ask for better code deletion support. Make it known that deleting code is just as important as writing it.

Can I Delete any more?

Yes. I’m still finding more to delete every week. We’re also trying to find ways to make it easier to delete on our backend, which is written in TypeScript and running on AWS Lambda, and that requires new ideas and new tools. I know at some point our deletions will also slow down when we remove the last of our deprecated code. Though the task of removing unused features will never end.

As our users needs evolve, we’ll also need to evolve. Adding features here and deleting feature there. But I know that we’ll be able to keep up as I’ve witnessed first hand how easy it is delete the unused code. I know that I will find lots of joy in the coming years bringing joy to our users, and to my coworkers.

1. If you’re interested in linters or just elm-review, checkout Jeroen’s blog, or follow him on Twitter.
2. While Elm does exclude unused functions and modules, it still includes unused record fields and values defined in let .. in blocks. Some of this can be removed by elm-review. Additionally, by applying JavaScript minifiers we can typically remove even more from a production build.

Nix for Dummies

I got a new computer recently and wanted to start off a little different. Traditionally I start setting up my dev stuff with things like nvm or Volta for managing my Node for my JavaScript projects. Then some pyenv for my Python projects. Throw in a bit of rvm for the Ruby projects. The list goes on and on. Every new project with a new language or new tool requires some new version manager.

On a brand new computer this is fine as you only have 1 project to begin with. After a few months or years though and it becomes a hassle to manage everything. So, this time I decided to try out Nix, which should hopefully 🤞make this easier.

---

I’ve been looking at using Nix for years now, but all of the tutorials I find go way over my head. I want something written for dummies like me. Something so straight forward a 5 year old could figure it out. The blog post that finally clicked for me is https://ejpcmac.net/blog/about-using-nix-in-my-development-workflow/. But I want something even shorter, so here is my quick intro to Nix.

---

• first, install Nix
• then, install direnv
• create a project
• inside your project directory, create a file named .envrc
• inside .envrc, write use nix
• inside your project directory, run direnv allow
• also inside your project directory, create a file named shell.nix
• inside shell.nix we’ll setup your project with one of the following

# For Node projects
{ pkgs ? import <nixpkgs> { } }:

with pkgs;

mkShell {
  buildInputs = [
    nodejs-18_x
  ];
}

# For Python projects
{ pkgs ? import <nixpkgs> { } }:

with pkgs;

mkShell {
  buildInputs = [
    python310
    python310Packages.black
    python310Packages.pip
  ];
}

# For Elm projects
{ pkgs ? import <nixpkgs> { } }:

with pkgs;

mkShell {
  buildInputs = [
    elmPackages.elm
    elmPackages.elm-format
    elmPackages.elm-test-rs
    elmPackages.elm-review
    nodejs-18_x
  ];
}

If these aren’t what you’re looking for, look for more options by searching for other packages.

---

1 month in and this process is still working for me. I have about a dozen projects on my new computer and haven’t had to worry about managing versions in any of them. I just move from project to project and everything is setup for me. Additionally if you use VSCode, I recommend adding this extension for working with Nix projects.

Keep Type(Script) out of my JavaScript

If you haven’t already seen it, the TypeScript team has put up a proposal to add type comments to JavaScript https://devblogs.microsoft.com/typescript/a-proposal-for-type-syntax-in-javascript/. Normally I don’t like to comment on language proposals, but this one happens to really bother.

Let’s start with the title “A Proposal For Type Syntax In JavaScript”. Unfortunately, that’s not what this proposal is, it’s for adding a new type of comment to the syntax, which some tooling can then be built to interpret as types.

Next is the misinterpretation of the proposal. I’ve seen across Hacker News, Lobsters, work chat, Twitter (from the TS official account), and more that this would “Could we have TypeScript with no build step? Could we have types in JavaScript? Maybe!” Except that’s not what this proposal is. It doesn’t allow you to get rid of TypeScript. It doesn’t remove bundlers or any of the other TypeScript tooling.

So then what does this proposal do if not put TypeScript in the browser/Node? Well, it adds a new comment syntax to JavaScript. The reason they give is that the current comment syntax isn’t sufficient for providing adequate type information. That we need additional comment syntax specifically for type information. But why? Why do we need comments for type information? Will it help me write better JavaScript? No, because it doesn’t actually affect JavaScript since it’s just comments. Will it make my app or website better for my users? No, if I don’t use a bundler then I’ll just be shipping even more code to my users, and if I’m using a bundler then I’m likely also not writing vanilla JavaScript.

So no, I do not want this proposal to pass. I see absolutely zero benefit to developers in this even being proposed, and I find it disheartening that the TypeScript team is being so misleading about what this proposal actually does.

Real World Software Development

The other day Jean Yang was talking about the difference between what developers talk about doing versus what we actually do day to day. So I figured I’d start documenting what I do, roughly, day to day.

---

To understand my role a bit better I should give some context. The first “real” code I ever wrote was in 6th grade. I had a basic web class and we made very minimal web sites. This was about the year 2000, so the web was still relatively young. Macromedia Shockwave and Macromedia Flash (this was before it was Adobe Flash) were all the rage. Custom cursors on your web page that sparkled were so awesome. I probably used some toy languages in before this too. I remember reading about Lego Mindstorms all the time and coding in my head. Both of my parents also gave me lots puzzles to solve, everything from more and more complex mazes to riddles and anything in between. Puzzles aren’t code, but they share a lot of the same skills that are required for programming and engineering.

In high school I stumbled across Visual Basic 6 and decided that I was going to be a programmer. From that point on I consumed everything I could about programming. I had a friend who taught me the basics of C and C++. I watched hundred of hours of tutorials on 3DBuzz (which is sadly no longer around). I learned some ActionScript in community college and Java, Standard ML of New Jersey, and some more C in college. I was also teaching myself C# both from 3DBuzz and from Unity3D tutorials. I was learning UnrealScript for making games with Unreal Engine 3. At my internship I was thrown into JavaScript for the first time, as well as real world C, C#, and Java.

During my internship I also started doing some indie game development in Unity3D with Digital Iris. This led me to a contract doing some work for Oculus as well as some experimental augmented reality projects. This indirectly led to my first full time software job working with JavaScript, using ExtJS and jQuery, as well as learning Perl, React, and a many, many other things. Since then I’ve also contributed to a Crystal package, contributed to Unreal Engine 4, worked on web apps deployed on TVs, and tons more even I don’t fully remember.

Today I work on the Developer Experience team at Square (obligatory these views are mine and mine alone and do not represent Square), working with documentation as well as Square’s various back end SDKs. Square supports 6 languages (Java, Ruby, Python, C#, TypeScript, PHP) with SDKs and uses a variety of languages internally. This means that on a weekly basis I’m reading code in roughly 7-9 different languages. If you include the languages I use at home for hobby development I’m probably looking at closer to 9-11 languages weekly!

Some people might think that this means I’m actually writing in nearly a dozen languages each week, but really I spend most of my time reading them. I have to read a lot of different code. Yes it can be a little funky sometimes to jump between say JavaScript and Elm. I do find myself writing parentheses in the wrong place every now and then. But really it’s not that bad. What’s significantly more difficult for me is variation within languages. If I’m reading Go or Elm, I know that every project I open is going to be formatted the same. This makes my day a lot easier. When reading nearly any other language, this isn’t the case. JavaScript is probably the worst offender here as almost no 2 projects are setup the same. Some use prettier, others eslint, some use both, others still use standardjs. Even when 2 projects use eslint odds are they have slightly different rules selected. This means that every time I open a JS project I have no clue what to expect formatting and style wise.

---

This week has been a lot of meetings and a lot of reading code. A tiny bit of actually writing code. I was reading a lot of C# trying to track down a bug. Reading and discussing C# and Java regarding implementation details of a feature. Lots of meetings about future work. Some writing of Go to implement a feature. This was ok, though I really wish Go had some way of writing generic checks for whether or not a value exists in an array. Had to have a lot of discussions about AWS setups because it’s really hard to know how a change in 1 system will affect others (shout out to Jean Yang for trying to make this better).

Because my team is all remote still we also do weekly 1-on-1s between a few of us to hang and chat. I also have monthly ones setup with a few prior teammates, just to catch up and see how things are going.

I’ve also had to read some Rails code which I am always slightly disappointed to do because it has its own unique idioms that I almost always have to spend time looking up. I also went back to writing some Ember, which I also struggle with because it also has unique idioms and they change almost yearly.

What I really would have wanted this week is not another web framework but better tooling for existing frameworks. Something that allows me to better understand how my code changes will affect both the local system and the system as a whole.

---

So that’s a day in my life as a software engineer. Very little coding and a lot of reading code and going to meetings. If you have any questions about my day-to-day or topics you’d like me to talk about, feel free to reach out to me on Twitter @wolfadex.

When All You Know is a Nail

The other week I was discussing the difference between what software developers consider a tool and what we consider a material. This came about because almost every developer I talk with ends up referring to everything they use as a tool. Their programming language, their editor, their hosting service, their keyboard, it’s all tools. I realized though in our chat that this doesn’t sit right with me.

When I think of tools I think of the things I use to create and separately there are the materials, the things that go into the actual project and remain there after I leave. When I knit my needles are my tools and my yarn is my material. When I work on my house my hammers, screw drivers, saws, and drills are my tools and the wood, nails, screws, drywall, and so on are my materials. When I garden my trowels, hoses, and buckets my tools and the water, soil, and plants are my materials. When I program my editor, computer, desk, email, and version control are my tools and the languages, frameworks, hosting services, are the materials.

This separation is important because too often I hear people say something like “When all you have is a hammer, everything looks like a nail. When all you know is JavaScript.” or whatever language you want to pick. But JavaScript, and any language for that matter isn’t the hammer, it’s the nail! Which would make the saying “When all you have is a nail, everything looks like …..?”, well I’m not sure. When the metaphor breaks down, or when even the understanding of what role something plays in the process breaks down, we can’t have meaningful discussions about the tools and materials we use.

My hope here is to shift the discussion a little towards the idea that the languages and frameworks we choose are like the bricks and mortar, wood and nails of our homes. They are not easily changed or moved and care should be taken when choosing them.