Welcome to my PinkLetter. A short, weekly, technology-agnostic, and pink newsletter where we cultivate timeless skills about web development.
My Ramblings This Week
Do you write code comments?
The Ruby style guide has a clear answer to that: NO.
Write self-documenting code and ignore the rest of this section. Seriously!
And then elaborates with:
Avoid writing comments to explain bad code. Refactor the code to make it self-explanatory.
Or as Tomasz Giereś, a good friend and colleague at work, wrote:
It basically tells you that you need to admit that your code is bad to have a right to write a comment.
Writing self-documenting code is an excellent northern star, but don’t take it as a rule. (As with anything that is called best practice.)
Instead, adapt your (and the team) style to the context you are in.
Working with a team of hardcore functional programmers? Go with FP, category theory, and papers. Working on a project that requires a ton of on-boarding of junior Ruby devs? Adhere to community guidelines. Working in a complex domain whose nuances are better expressed in plain English? Throw a comment in there.
In other words, create your team playbook!
Elsewhere on the Web
Get your work recognized: write a brag document by Julia Evans
There’s this idea that, if you do great work at your job, people will (or should!) automatically recognize that work and reward you for it with promotions / increased pay. In practice, it’s often more complicated than that – some kinds of important work are more visible/memorable than others. It’s frustrating to have done something really important and later realize that you didn’t get rewarded for it just because the people making the decision didn’t understand or remember what you did. So I want to talk about a tactic that I and lots of people I work with have used!
Haskell for the Elm Enthusiast by NoRedInk
Rails has served us well and has supported amazing growth of our website, both in terms of the features it supports, and the number of students and teachers who use it. But we’ve come to miss some of the tools that make us so productive in Elm: Tools like custom types for modeling data, or the type checker and its helpful error messages, or the ease of writing (fast) tests.
A couple of years ago we started looking into Haskell as an alternative backend language that could bring to our backend some of the benefits we experience writing Elm in the frontend. Today some key parts of our backend code are written in Haskell. Over the years we’ve developed our style of writing Haskell, which can be described as very Elm-like (it’s also still changing!).
How MDN’s autocomplete search works by Peter Bengtsson
Last month, Gregor Weber and I added an autocomplete search to MDN Web Docs, that allows you to quickly jump straight to the document you’re looking for by typing parts of the document title. This is the story about how that’s implemented. If you stick around to the end, I’ll share an “easter egg” feature that, once you’ve learned it, will make you look really cool at dinner parties. Or, perhaps you just want to navigate MDN faster than mere mortals.