DEV Community: Aha!

Building a dynamic Canvas rendering engine using JSX

Percy Hanna — Tue, 02 Apr 2024 15:59:38 +0000

Our product team is busy adding many great new features to Aha! Whiteboards and Aha! Knowledge — including wireframes, voting, and improvements to viewing Aha! Roadmaps data within a whiteboard. We added all of this functionality in just the last few months, and we are busy building even more features that will deliver product value to our users.

As the engineering lead for these products, I saw all of the above features (and others) on our product roadmap and had a few thoughts:

How can we easily build features that rely on dynamic content and real-time user collaboration?
How can we do that on Canvas? Rendering dynamic content on Canvas is complicated — or at least, it's much more difficult than using HTML and React, which is how we have built most interactive features at Aha!

The challenge

Anyone who has used Canvas in the past understands the challenge. You cannot simply render content to the screen — you must manually draw content using functions such as lineTo, fillRect, fillText, and so on. Consider the really simple example of rendering "Hello, world!" with basic styling and a quick layout. Let's try and reproduce this HTML in Canvas:

<span style="border: solid 1px black; padding: 5px; font: 16px Times;">
  Hello, world!
</span>

The code above will produce this:

But let's see what we would need to generate this in Canvas:

// Rendering context
const ctx: CanvasRenderingContext2D = canvas.getContext('2d');
const padding = 5;

// Measure the text
ctx.font = '16px Times';
ctx.textBaseline = 'top';
const textMetrics = ctx.measureText('Hello, world!');

// Calculate the box size
const contentWidth = textMetrics.width + padding * 2;
const contentHeight = textMetrics.fontBoundingBoxDescent + textMetrics.fontBoundingBoxAscent + padding * 2;

// Draw the border
ctx.fillStyle = 'black';
ctx.strokeRect(0, 0, contentWidth, contentHeight);

// Render the text
ctx.fillText('Hello, world!', padding, padding + textMetrics.fontBoundingBoxAscent);

Almost 20 lines of code just to render the most basic of content.

Dynamic content

This becomes even more complex when you start adding dynamic content. For example, one of the first features in our Aha! Whiteboards roadmap was to add emoji reactions to our sticky note shape. This is a simple way to gather feedback from everyone viewing the whiteboard. The feature seems simple enough. In React/HTML, you might have something that looks like this:

<button className="emoji-button" onClick={clickHandler}>
  👍 1
</button>

And here is what the user would see:

In Canvas, this becomes much more difficult. We have to render the button, add the padding and border radius, and then render the emoji and reaction number.

But it doesn't stop there: What if 10 people react with a thumbs-up? Or 100? Now, that button must be wider to adapt to the content inside of it. In HTML, you don't even have to think about this. It just happens. You would just write your code like this:

<button className="emoji-button" onClick={clickHandler}>
  👍 {counter}
</button>

Chances are that's how your component was written in the first place. You didn't even think about how to resize the button element — the browser's rendering engine just did that for you. Emoji reactions was just the first feature I saw in our roadmap. And there were many others. But the big, daunting one was wireframes.

Not only did we need a way to render a button that was entirely in our control, but we also needed to allow users to create their own buttons and add their own content to it. And a button was one of the simpler components we needed.

The naive solution

The very naive solution would be to write each button and wireframe shape separately. You could perhaps create a renderButton function as a helper to render a button to the Canvas. Generalize the above code into a function, and you come up with something like this:

// Rendering context
const ctx: CanvasRenderingContext2D = canvas.getContext('2d');

function renderButton(text: string, padding = 5) {
  ctx.save();

  // Calculate the box size
  const textMetrics = ctx.measureText(text);
  const contentWidth = textMetrics.width + padding * 2;
  const contentHeight = textMetrics.fontBoundingBoxDescent + textMetrics.fontBoundingBoxAscent + padding * 2;

  // Draw the button background
  ctx.beginPath();
  ctx.roundRect(0, 0, contentWidth, contentHeight, 4);
  ctx.fill();

  // Render the text
  ctx.fillText(text, padding, padding);

  ctx.restore();
}

But this solution is limited. It only solves a specific problem and doesn't help fill in the functionality gap that HTML addresses out of the box. Imagine how this would scale as you add more complex shapes like these:

Navigation menu:

Dropdown picker:

So the complexity of rendering all of these wireframes grows quickly, even with relatively simple shapes. How do you calculate the width and height of each navigation item? How do you render the borders, backgrounds, and dividers between each item?

Buttons

Let's take a deeper look at a very simple shape we have in our Wireframes: the button. As I demonstrated above, implementing a basic button renderer would not be difficult in and of itself. But there is already a bit of added complexity here. Our button needed to support multiple styles:

Style	Example
Basic
Rounded
Outline
Rounded outline
Link

Each of these variations adds a bit more code and complexity to our renderButton function. It would definitely be possible to support all of these designs with a single function, but would it be elegant? Reusable? Dynamic?

Did you notice the icons? Well, users can choose to place the icon on the right side instead. And they can change the color of the button and the text, too. By themselves, each of these are minor things to add. But eventually, that function would become overloaded with all the variations, customizations, and edge cases that need to be handled.

JSX

In order for our team to be able to easily implement all of these features, we needed a readable, elegant, and powerful way to render dynamic content to Canvas in a familiar way. I thought to myself, wouldn't it be great if we could just render content to Canvas the same way we do with React?

And then I had my Aha! moment. WE COULD! To do this, we would use one of the really powerful and innovative features that React introduced to the world — something called JSX. It's really just syntactic sugar to write HTML syntax into declarative and well-structured element objects. For those of you who are unfamiliar with JSX, what it does for you under the hood is convert code like this:

<button className="emoji-button" onClick={clickHandler}>
  👍 {counter}
</button>

Into something like this:

_jsx('button', { className: 'emoji-button', onClick: clickHandler }, '👍 ', counter);

JSX, in my opinion, was the biggest innovation that came out of React given that you could write HTML directly in your JavaScript. I had used other frameworks such as MooTools in the past. You could use them to dynamically construct HTML in JavaScript, but with a very verbose and tedious syntax. It looked very similar to the converted code above. And it worked, but it was not satisfying or pleasant.

The beauty of JSX is that you can override how elements are converted to JavaScript code using something called a pragma. A pragma, or directive, is something that tells the JSX compiler how to process the code. In your JSX/TSX code, you can add a pragma to the top of your file like this:

/** @jsx CanvaSX */
import { CanvaSX } from 'canvasx';

Now, instead of converting your JSX to React code, the above code would be converted to something called CanvaSX code (more on this later):

CanvaSX('button', { className: 'emoji-button', onClick: clickHandler }, '👍 ', counter);

The solution

My goal was simple and clear: I wanted to be able to write JSX code that could render a simple navigation/tab menu. The system should generate the layout and render that content for me dynamically, and I shouldn't have to think about the complexities of measuring text and padding and layouts. It would need to handle very common layout patterns such as margin, padding, (rounded) borders, and so on.

The really powerful feature would be to have all the layout complexity completely hidden from the developer. When rendering the navigation items, the width of each item would need to be based on the text and/or icon inside it, and then the borders and background should be rendered based on the width of that content. We would then need to render dividers between each item.

Introducing CanvaSX

I spent some time prototyping a rough implementation of a rendering engine that I've come to call CanvaSX (Canvas+JSX). The early versions were quite rough, but the benefits were obvious. I could write simple shapes like a button or navigation menu using very familiar syntax, and I didn't even have to think about calculating coordinates or layouts.

Eventually, I added support for basic interaction properties (such as onClick and tooltip handlers) and some very rudimentary flexbox-like components, too. Now, we could have something like a real button completely rendered in Canvas. The end result made the emoji button as simple as this code:

<Rect
  fill={backgroundColor}
  borderRadius={2}
  padding={2}
  onClick={emojiClickHandler}
  tooltip={emojiTooltipContent}
>
  <FlexRow gap={2} verticalAlignment='center'>
    <Emoji shortCode={shortCode} />
    <Text color={textColor}>{votes}</Text>
  </FlexRow>
</Rect>

Which made sure we could offer reactions like these:

The wireframe button is very similar, but it simply passes along user input to the properties. For example, to support rounded vs. square buttons, we just need to write something like this:

<Rect
  fill={backgroundColor}
  borderRadius={round ? 32 : 4}
>
  <Text color={textColor}>{text}</Text>
</Rect>

This code is very easy to read for anyone familiar with React, and CanvaSX addresses all of the layout complexities.

How does it work?

The magic behind CanvaSX is that every component can measure itself. With this information, CanvaSX can generate the layouts automatically. This is what the Text component's measuring function might look like:

Text.calculateDimensions = (props, ctx: CanvasRenderingContext2D) => {
  ctx.save();

  if (props.font) {
    ctx.font = props.font;
  }

  const textMetrics = ctx.measureText(props.children);

  ctx.restore();

  return {
    width: textMetrics.width,
    height: textMetrics.fontBoundingBoxAscent,
  };
};

A parting note

Building CanvaSX is one of the highlights of my career. I have had the opportunity to work on many features in my more than five years of working at Aha! These include capacity planning for teams, redesigned drawers, Aha! Develop, and our custom card layout editor. I've recently worked on many improvements to Aha! Whiteboards, which is where CanvaSX came in. It has proven itself to be extremely powerful and flexible — and it is now used as the foundation for emoji reactions, wireframes, updated record cards, and our brand-new voting tool!

I work with a team of extremely talented engineers at Aha! We collaborate to solve hard problems and deliver value to our users. If this sounds like something you would enjoy doing, you should check out our open positions.

Ruby enumerables considered helpful

Justin Weiss — Thu, 12 Oct 2023 19:36:12 +0000

Ruby's Enumerable methods help you make powerful code simple — by filtering, transforming, and processing data like the best engineers do. These methods are available on Arrays, Hashes, and many (many) other objects, and similarly-named methods are available on even more. If you don't already know these methods well, then the most valuable time you can spend in Ruby is on mastering them.

But not all data can take advantage of Enumerable methods, at least not directly. What if you don't have an Array or Hash? Can you still use the Enumerable methods? With all the time you spent becoming an Enumerable master, wouldn't it be nice if you could treat more things like Enumerables — like lists of items across multiple pages, or even items that slowly stream in from an API over time?

Ruby's Enumerator class is exactly what you need to do this. It's not the easiest thing to understand, but a few examples can show you how to use it in your own applications.

Automatic pagination

Sometimes your data seems like a natural fit for an Enumerable, but it doesn't quite work. What if you're using an API that paginates? The best you can get is an Enumerable per page, which makes it annoying to work with multiple pages at once. You could fetch all the pages and then flatten the list of lists… But now you're always fetching all the data (even if you don't need it) and you have to wait for every page to load before you can do anything.

Instead, wrap your API calls in an Enumerator:

def paginated_list(initial_url, params = {})
  url = initial_url

  Enumerator.new do |yielder|
    # ...
  end
end

This returns an Enumerator, an object that can be used like an Enumerable, responding to all of the core Enumerable methods you know and love: map, filter, first, and all the rest.

When you call a method like map on that Enumerator, that method will ask for the next object as it needs it. When asked, the body of the Enumerator yields the next object using the yielder:

def paginated_list(initial_url, params = {})
  url = initial_url

  Enumerator.new do |yielder|
    loop do
      response = get(url, params)

      body = response.body

      # Yield each result to the caller
      body["results"].each { |result| yielder.yield(result) }

      break if last_page?(body)

      # get ready to fetch the next page
      url = next_page_url(body)
    end
  end
end

This Enumerator makes the request for the first page. Then, any time a record is needed from the first page, the Enumerator yields it to the caller. When you run out of records on the first page, the Enumerator fetches the next page and so on until you run out. If you don't need the next page, it won't fetch it.

How does this look for the caller?

paginated_list("/things").filter { |t| t["selected"] == "true" }.sort_by { |t| t["name"].downcase }

Easy — you don't even have to care that the data spans multiple pages across multiple API requests. From the caller's point of view, it's just an ordinary list.

Save a block for later

While working on the Aha! AI writing assistant, we had two different ways of working with AI responses. For development and testing, the response should be returned all at once because it is easier to work with. For a user, though, it feels better for the response to arrive incrementally — streaming in so you can know early on if you're getting the result you wanted.

Everything else was exactly the same, except for how the response was dealt with. In one case, a string was returned. In another, bits of a string were yielded to the caller as they came in:

client = Client.new(stream: stream?)

# Burst response
response = client.get(query: params[:query], context: params[:context] ...)
render json: { text: response }

# Stream response

# all kinds of streaming setup work
client.get(query: params[:query], context: params[:context] ...) do |chunk|
  # stream chunk to browser
end
# all kinds of streaming teardown work, stream error handling, etc.

This is fine. But the API method calls look exactly the same, except one takes a block and the other doesn't. And for streaming, you have extra work to do before and after the method call.

It's hard to untangle this. You could pass around lambdas, get could ignore a lambda parameter in stream mode, you could wrap the setup and teardown in its own block:

client = Client.new(stream: stream?)

response = streaming_setup(stream?) do
  client.get(query: params[:query], context: params[:context]) do |chunk|
    # stream chunk to browser
  end
end

render json: { text: response } unless stream?

Maybe this will work. Again, it's fine. But this is Ruby, so we can do better than fine.

Object#to_enum is a method available on any object. You give it a method name and arguments and it returns an Enumerator. Whenever that Enumerator is enumerated, it will call the method you gave it, on the object you called it on, with the arguments you gave it, and it will pass along anything your method yields as the next value of the Enumerator.

At first, it's hard to see how this is useful. In practice, this means you can capture the arguments a method was called with, but defer needing the block the method yields to until the part that processes your data needs it.

Using to_enum, the caller can now look like this:

def show
  client = Client.new(stream: stream?)

  response = client.get(query: params[:query], context: params[:context])

  if stream?
    stream_response response
  else
    render json: { text: response }
  end
end

def stream_response(response)
  # all kinds of setup work
  response.each do |chunk|
    # stream each chunk to browser as it arrives
  end
  # all kinds of teardown work, stream error handling, etc.
end

client.get now returns either a string or an Enumerator. If it's an Enumerator, it will yield each part of the response as it's received. Because this code no longer needs the block at the same time as the arguments, all of the logic around streaming a response can go somewhere else. This is much less tangled up than the last version. How is this possible? By using to_enum in the client when it's not given a block:

class Client

  def initialize(stream:)
    @stream = stream
  end

  def get(query:, context:, &block)
    if @stream
      get_stream(query, context, &block)
    else
      get_burst(query, context)
    end
  end

  def get_stream(query, context, &block)
    return to_enum(:get_stream, query, context) unless block_given?

    some_api_request do |chunk|
      # ...
      yield chunk
    end
  end

  def get_burst(query, context)
    # nothing interesting here, just a basic request and response
    response
  end
end

If the client is in streaming mode and isn't given a block, get_stream returns an Enumerator that calls get_stream with a block. The yielded chunk is passed back through to the Enumerator when the caller, or any other code that the caller hands the Enumerator to, uses it.

This pattern — decoupling the place where you need the arguments from the place where you have the block — becomes even more powerful the further apart those places are separated. It's a nice pattern to understand, and it's possible because of Enumerators.

Enumerators can be tricky at first. It's hard to see the use when you read about them in the docs. But they have an amazing ability to wrap Ruby code into objects that take advantage of the full power of Enumerable methods. It's valuable to use the knowledge you already have in more places, and Enumerators will help you do exactly that.

CLI tools at Aha!

Steve Lamotte — Mon, 14 Aug 2023 16:55:19 +0000

Take your command-line utilities to the next level with these Ruby gems

Ruby has always been a great general-purpose scripting language and is often used to create command-line utilities. Many of these use the excellent
Thor gem to parse command-line options, but there's no escaping one fact: command-line utilities just aren't interesting. Never have been, never will be.

However, since Ruby was released in 1995, developers have created some clever and useful libraries for making command-line utilities simpler to use, look at, and code.

I love creating command-line utilities

I am part of the Aha! platform team. Our primary focus is ensuring system reliability, but we are also responsible for providing developer tooling for the rest of the engineering team. One of our main tools is the ops
command-line utility that performs many mundane yet important tasks to simplify processes for our engineers. Here are a few examples:

ops ecs deploy deploys an application to an AWS ECS environment
ops ecs ssh launches a shell on an existing application container
ops ecs shell spins up a new application container and launches a shell there

As we make updates to our ops and similar CLI utilities, we often improve the user experience by taking advantage of various Ruby gems. With little effort compared to low-level coding with curses, our command-line utilities that used to be cryptic and confusing are now interactive, easy to use, and — dare I say — elegant.

Let's talk about a few of these "gems." 😆

1. `cli-ui`

I really enjoy using the cli-ui gem. It offers a lot of powerful, intuitive features including:

spinners: provide feedback that something is happening (e.g., track the progress of multi-threaded operations)
frames: clearly demarcate logical groups of output including the ability to nest frames within each other
prompts: provide a powerful UI for displaying and selecting a list of choices
text formatting: provides several helpers to make text formatting quick and easy

When we deploy code at Aha! we kick off a number of AWS CodeDeploy tasks running in parallel. Here's some code to simulate deployment:

require 'cli/ui'

def deploy(build)
  CLI::UI::StdoutRouter.enable
  CLI::UI::Frame.open("Deploying Aha! build #{build}", color: :blue) do
    CLI::UI::SpinGroup.new do |spin_group|
      spin_group.add("pod1") { sleep 2 }
      spin_group.add("pod2") { sleep 3 }
      spin_group.add("pod3") { sleep 1 }
    end
  end
  puts ;
rescue StandardError => e
  puts CLI::UI.fmt "{{red:Deploy failed: #{e.message}}}"
end

deploy "123"

This produces the following output:

Obviously, our deploys aren't quite this fast or simple. But you can imagine how useful it would be to see output with feedback like this when you have dozens of long-running threads executing in parallel, like our real deploys.

2. `terminal-table`

I used to write a lot of custom code to format tabular data in my CLI utilities. Thankfully, that stopped once I discovered terminal-table.

This gem is very easy to use and can process arrays as well as CSV data. Here's a quick example showing how simple it is to create nicely-formatted tabular data:

require 'terminal-table'

table = Terminal::Table.new do |t|
  t.title = "Shipment Summary"
  t.style = { border: :unicode_round }
  t.headings = ["Product", "Quantity", "Unit Price"]
  t.rows = [
    ["Apples", 500, "$1.99"],
    ["Milk 2% 4l", 100, "$4.99"],
    ["Rye Bread", 25, "$3.99"],
  ]
  t.align_column(1, :right)
  t.align_column(2, :right)
end
puts table

The output is simple yet quite aesthetically pleasing:

Not too shabby!

3. `ombre`

Finally, here is a nice little gem created by Aha! director of software engineering, Justin Paulson. Ombre provides a fun way to spice up your output by rendering text with a gradient. Here's an example that prints zombie ipsum with a red, white, and blue tint:

require 'ombre'

puts Ombre.horizontal(<<TEXT, ["FF0000", "FFFFFF", "0000FF"])
**********************************************
* Zombie ipsum brains reversus ab cerebellum *
* viral inferno, brein nam rick mend grimes  *
* malum cerveau cerebro. De carne cerebro    *
* lumbering animata cervello corpora         *
* quaeritis. Summus thalamus brains sit,     *
* morbo basal ganglia vel maleficia?         *
**********************************************
TEXT

This produces a colorful output:

We use Ombre to display a banner when we launch CLI tools that help us create pull requests:

While this banner doesn't add any measurable value to our utility, it helps reinforce a sense of team spirit every time it's displayed.

Be sure to add these new gems to your Ruby command-line arsenal. They have great documentation — and are fun to use — adding a little panache to your command-line utilities.

12 Tools for Quality Pull Requests

Chris Zempel — Thu, 29 Jun 2023 19:12:02 +0000

As you stare into an empty text field, the blinking cursor invites you to engage in a crucial part of being a professional software engineer — writing a pull request. What will you write? Almost every idea you will come up with is downstream of the habits you've cultivated and the information you've consumed. Your attention to your upstream (or lack of) will define your practice — your customary, habitual way of doing something.

How is your practice of writing pull requests? On one hand, you will improve as you engage in shipping work as part of a team because you'll be repeating the act of writing and reading pull requests. On the other, occasionally applying conscious and deliberate attention to your practice will yield large and rapid improvements. This is when you work on your upstream — the habits, tools, and techniques you lean on when you start authoring a pull request. Often, this is harvesting your experience to see and think in relevant ways you couldn't before. Sometimes, though, the world sees fit to make it really easy on you.

My teammates recently put out some pull requests which were so nice they (metaphorically) shook me by the shoulders and shouted "you should also be doing this!" Before I can share with you exactly what they did, you must also understand a fuller picture. Sometimes beauty is the lack of something. Appreciating the lack of something is hard if you don't know it is supposed to be there. But when you understand the goals of writing a pull request, it then becomes possible to know which elements you can remove.

What is a quality pull request?

Quality means consistently meeting spec. For our pull requests, this means "do I have the right reviewers?", "do reviewers have all the information they need?", and "will someone looking at this in the future be able to access the 'what' and 'why' behind the 'how' of this implementation?"

Notice these are questions, not advice. Questions are resilient and adaptable to context. Advice is brittle. The best tools to keep in your upstream are the right questions.

Also notice this has nothing to do with "perfect." While it is tempting to focus on how you can write the perfect pull request, this is the wrong question. A focus on perfectionism is a great way to hide, hedge, and never ship. Or, perhaps more insidious, continually spend lots of wasteful effort when you could instead be learning how to achieve the same effect with less effort.

The goal is a durable, refined practice you can lean on to write a pull request that meets spec in the shortest amount of time.

Tools for writing pull requests

Here is a cheat sheet I use to write quality pull requests, quickly. And below I explain my thought process for each question so you can start using this in your own work.

#Cheat Sheet

On Writing

[ ] Do I have all the right reviewers?
[ ] Do reviewers have all the information they need?
[ ] Is my information organized in descending levels of scale?
[ ] Will someone looking at this in the future be able to access the "what" and "why" behind the "how" of this implementation?
[ ] Can I clarify my title for other contexts using prefixes, conventions, or other keywords?
[ ] Is there supplementary information I could add as footnotes?

Using Details Tags

You can hide nonessential information using details.

Example:

<details><summary>Toggle me!</summary>Peek a boo!</details>

Adding Footnotes

Here is a simple footnote[^1]. With some additional text after it.

At the bottom of your pr:

[^1]: My reference.

On Structural Artifacts

Should I include some kind of diagrams, illustrations, or screenshots?

✅ substantially modifies code with a lot of branches of essential complexity
✅ includes a large amount of discrete before/after states
💡Integrate this element of your practice earlier into your development to minimize effort

On Responding

[ ] Am I coming at this from the right mental frame?
[ ] Does my feedback block approval?
[ ] Could this be phrased as a question or observation?
[ ] Is this a nit?
[ ] Does my review include something I like?
[x] If you don't know what to say but you like it, just use ✨.

Going deeper

Do I have all the right reviewers?

Maybe security, or your platform team should look at this. Perhaps this change will impact another team's functionality, or there's a specific subject matter expert who will be able to tell you information you didn't even know you should think about.

Do reviewers have all the information they need?

This is figuring out what information you need to include. One big tell you should mention something is when you're surprised by a piece of information not otherwise indicated in the code. At the least, this information should be present in your pull request. Other information that's usually good to include? The strategies you used to implement, and maybe even the ones you tried and then threw away. Perhaps it is worth explaining the behavior of the system prior to your change.

Ultimately, how well you do this depends on your wisdom. Wisdom is the ability to correctly predict the future in a specific context. Pay attention to what questions you're asked and what information others seek. Over time, you will learn what you don't need to say. I've noticed that at Aha! we often don't need to include lots of detail on bug fix pull requests. There is the problem, a link to the bug tracker, and a fix contained in the pull request. Unless the fix is nonintuitive, this often adequately expresses all the information a reviewer needs to make an informed decision.

Is my information organized in descending levels of scale?

You've determined what information needs to be present. Now you must determine how to arrange it. This generally means some combination of:

Prior system behavior — useful in pull requests addressing bugs with nonobvious fixes
What the key abstractions are and why they were introduced — provides a mental anchor for your reviewers to understand and contextualize what code they are seeing
Little big details — is there system behavior, or other finer-scale details which have an impact on the large-scale design of the system? This is worth prioritizing and highlighting earlier on.

Will someone looking at this in the future be able to access the "what" and "why" behind the "how" of this implementation?

This presupposes you have a system in which you track your work. In each pull request, we link back to the record which caused the work. Many of us include the record's reference identifier in our commits, and we have an in-house CLI tool which will conveniently branch off wherever we're at and include the reference identifier in our branch name (and thus our default pull request name). Internally, we colloquially refer to these records as "features."

If you have never had this experience, let me tell you: it is amazing. Being able to look through the contents and history of the shaping feature allows you to understand what was intended by the code change and why the change was introduced. Knowing this has helped unstick me many many times because I am able to confidently distinguish what code we no longer need and what we must keep.

Instantly recalling context from people I've never met 5+ years ago is just cool. I've started using Aha! Develop for personal work and side projects for access to this form of extended personal/organization recall.

With these bases covered, let's look at ways you can represent finer scale details.

Can I represent this detail with a comment?

When there is detail which only makes sense when you're also considering some specific code, include the detail in the code. For example:

"The space that needs to be added to text is now added <other place>."

Or perhaps you've introduced a finer-scale abstraction or refactor that's only worth calling out the first time a reviewer will reach that line of code.

We do if information.fetched? && information.company_name? many times in the templates, so I'm adding a convenience method.

Can I hide nonessential information using `<details>` ?

If there are pieces of information in your pull request that aren't essential for the first time someone's reading it, you can hide the information inside a <summary> component. I often use this for quick scripts to set up the system in a certain state, or for deeper explanations of a given topic.

<details>
  <summary> How do `details` work? Simple. </summary>

  You have your summary, and your details.
</details>

Is there supplementary information I could add as footnotes?

GitHub added support for markdown footnotes. This is a great feature that lets you include supplementary information which does not fit well inside the main text.

Quick reference:

Here is a simple footnote[^1]. With some additional text after it.

More advanced use, sourced from the linked GitHub post

Should I include some kind of diagram, illustration, or screenshot?

If your pull request substantially modifies code with a lot of branches of essential complexity or includes a large amount of discrete before/after states, consider building some sort of informational aid for your reviewers.

I've found myself reaching for whiteboards on multiple features recently. Whiteboards make it really easy to flowchart and enumerate the intended execution.

Even just in GitHub-flavored markdown alone, you can create some pretty incredible pull requests.

Putting these together during development while the information is already in your head isn't a lot of extra effort for you. Doing so can produce a tremendous reduction in effort for your reviewers.

When revisiting older code, a visual cue can quickly remind the reader what this feature looks like, and trigger memories about related context they might have.

Can I clarify my title for other contexts?

Often your pull request's title will be the main piece of information that others see in systems outside where you keep your code.

When I have a feature that spans multiple repositories, I often update my titles to include the repo name in brackets up front so it's easy to keep straight.

PIZZA-2022 [pizza-design-system]: upgrade toppings to level Infinity and Beyond
PIZZA-2022 [pizza-app]: upgrade toppings to level Infinity and Beyond (PIZZA-2022 is the format of our Aha! feature reference numbers.)

Other pieces of information you might want to consider updating with:

Include important keywords to help with searching
Use a consistent convention such as feature ID prefixes
Name the "what" or "why" instead of the "how"

Tools for responding to pull requests

Am I coming at this from the right mental frame? It is easy to fall into the emotional trap of over-identifying with your work — causing you to beat yourself up as a failure over each change request. Or maybe you're setting your expectations to a place where change requests will make you feel resentful that you didn't receive approval instead of grateful someone is trying to make your work better.

Consider that someone else is spending their life and attention understanding your work and helping you move it forward. Often, these are extremely experienced and skilled peers. Think about a time before, when you were newer, when your sole desire was to learn and improve. What would you have done to get this kind of generous feedback? What would you have given? Then think about now. What's actually different? Nothing.

We're all human. Sometimes there's deadlines or other kinds of pressure. If you find yourself emotionally reactive, don't type anything. Step away. Take a moment and figure out why you're feeling the way you are. Chances are you're being too harsh on yourself. Be kinder to yourself, or reach out for support.

The goal is consistently shipping quality work with your team.

Could this be phrased as a question or observation?

This is a technique I picked up at Aha! which I then realized was pervasively used by effective open source contributors. Once I became cognizant of this technique, I now see it everywhere.

When you're not sure you have full context, or want to soften your feedback, phrase it as a question. A question might be:

Could we inline these styles instead of modifying our webpack config for just this one place?

Where an observation would be:

I noticed in my testing that in <some conditions> I'm still seeing <cookie that shouldn't be there>.

Phrasing your feedback in terms of questions or observations is humble and generous. It leaves space for what you might not know and keeps the focus on the work you're doing with your teammates. Not on who was doing it.

More examples:

Is the property relevant at all? Not sure what that distinguishes.

Can this be private, maybe others too?

The reason why questions are so effective is they create a conversational loop where you can make progress with someone else. This keeps momentum up and the focus on the work you're doing together. Addressing the question, implementing feedback, clarifying context, etc.

Such change suggestions can still be submitted with a go-for-launch approval if the code is still going to be improved in the near future. The author can choose whether to address it now, or potentially later.

Does my feedback block approval?

If you have feedback that requires change and you're certain it's necessary, use an active voice and explain your reasoning. This could be a simple bug, a small refactor, or a large need. Either way, if you have feedback that will block code approval, make this clear.

This is a moment when you can be especially generous and raise the skill level of your team. Here is an example of some particularly good feedback:

It's better to test the call one more layer down the stack instead of the private method, as the private method can be refactored now without potentially breaking the dependency on the Tracker layer below.

That tracker_stubbed config is defined here and just DRYs up the boilerplate.

This feedback explains "why" and "what," then provides guidance on "how." I tend to reserve this for situations where I have absolute certainty, the existing implementation is otherwise functional, and I can't easily phrase it as a question.

Is this a nit?

A nit is a small, non-blocking and potentially opinionated change suggestion. I find it is best to call these out directly as a nit:

nit: this method seems awfully similar to SomeClass#this_other_method. Could we use that instead?

nit: why not !private? instead of listing every other option?

Using language which directly implies this is a nit and maybe we want to do it (at the author's discretion):

Maybe a better way to access this:
<code example>
I think this will also give you the titleized version, removing the need to call toUpperCase below.

Or it is a personal preference:

I prefer to do <thing you're doing> like this:
<code example>
Because then you get x, y, and z.

Does my review include something I like?

It's easy to end up only commenting on things to be critical of. Take time to acknowledge the parts that are good, too.

When you see something you like, say it. If you don't know what to say but you like it, use ✨.

I really like how <thing is working>

Thanks for the well-reasoned approach here

Those capybara specs 💯

Nice. Bonus points for meme style.

Choose tools to support your purpose

Remember, the goal is a durable, refined practice you can lean on to write a pull request that meets spec in the shortest amount of time.

Questions are resilient and adaptable to context. Advice is brittle. The best tools to keep in your upstream are questions.

Here is the cheat sheet

Aha! is happy, healthy, and hiring. Join us!

This blog post only exists because of efforts of other engineers on the team. I stopped multiple times in the middle of reading a pull request with the recognition 'this is so well done.' These moments prompted me to dig in further to understand what specific techniques were causing this reaction in me. If you want to build lovable software with this talented and growing team, apply to an open role.

Solving a critical bug in the default Rails caching library

Andrew Jones — Mon, 08 May 2023 21:24:30 +0000

An odd coincidence

On March 20th, ChatGPT users reported seeing conversations that were not their own. Just a few weeks earlier I had solved a bug where the default Rails caching library (Dalli) would return incorrect values. I thought, "this ChatGPT incident sounds a lot like what could happen with that caching bug via returning incorrect cached HTML." But OpenAI doesn't use Rails so I shrugged the thought off as recency bias.

My jaw dropped when I saw the postmortem — it was exactly the same bug concept, just in a different library! A reminder that hard things often transcend particular languages and libraries. And boy, is this a hard bug. It sits at the intersection of caching, shared resource management, and state corruption — infamously tricky problem spaces.

The bug mechanism

The Dalli caching client connects to a memcached server with a socket (which is essentially just a buffer, I'll use the terms interchangeably). The client issues a get message to the server which says "give me the value for this key". In response, the server writes some data into the socket buffer. The client then reads bytes off of the socket until it has processed one complete response, making the assumption that what it's reading is the response to its own get message. If the socket was empty at the beginning of the operation, that assumption works and the client returns the correct cache value.

But what if the buffer was not empty when the client issued the get command? Then the client processes the data that was on the socket as if it were the requested value, and — since no extra validation steps occur — returns the wrong value for the given key. Worse, because it would only read one value's worth of data out of the buffer (it knows when to stop reading based on a metadata header), the actual response to its request would remain on the socket for the next request to return incorrectly, and so on.

The socket has thus entered an indefinite "off by one" corrupt state. Meaning the nth get operation will return the value for the n-1th operation's key, leaving its own value in the buffer for the n+1th to read. Oh no! That corrupted state in a different library explains ChatGPT's incident.

If your cache system starts returning the wrong values that's very scary from a security perspective, because data or HTML cached for one user might be shown to another user. In the case I saw firsthand this didn't happen because the incorrect cache values all type mismatched, causing the process to error repeatedly until it was killed. That was lucky, but a Rails app conceivably could see the exact kind of incident OpenAI saw. It would just depend on what type of data was on the corrupted socket and how the application uses the cache.

How it happens

Why would there be an unread value in the buffer? All that's required is for the client to send a get command to the server and then fail to actually read the response — while also leaving the socket around for a future request to use.

One way this might happen in Dalli is if there's an issue in get_multi code. This could occur if the client requests multiple values, reads some subset of those values off of the socket, and then returns before the server finishes writing all of the values to the socket. Another way this might happen is if something - say, an error or a timeout - interrupts the client code execution between issuing a get message and reading the response.

Ideally the client would discard/reset the socket in case of an error or timeout, and in most scenarios that's exactly what would happen. But all it takes is one code path where the socket can get corrupted and stick around. Unfortunately, there is at least one such a code path, explaining the incorrect caching behavior I observed.

The specifics are less important than the question of whether the client should rely completely on the assumption that the socket will be empty when it begins a get operation.

The fix

As a security engineer I love when I can solve a bug deep in an abstraction, making it impossible for a developer using the abstraction to cause the bug again — even if they make a mistake. We should encourage developers to avoid known dangers, sure, but it's best for an abstraction itself to prevent unacceptable outcomes automatically. Or, within the abstraction, we should try to manage our state correctly, but it's best if we can preclude the worst impacts even if there's a flaw and some unexpected state emerges. It is far more robust to make a failure case impossible at the root instead of relying on all the higher level code doing the right thing every time.

To that end, I pursued a simple foundational fix. Memcached has a getk command, which differs from get by returning the key alongside the value. The downside is a small performance cost — returning the key means processing more bytes. The upside is that the client gets both the key and the value back from memcached, and can check that the key matches what it asked for.

That's the core of my implementation - if the keys don't match, raise an error. Simple. Now even if the buffer contains a leftover value for a different key, the client won't return it. Instead it will reset and retry.

Analyzing the fix

What of the cost vs benefit? In the context of a multi-tenant Rails application, it is generally not an acceptable risk to potentially expose one tenant's data to another, even in a low probability event. A small increase in overhead to completely rule out a data exposure bug is a small price to pay.

In this case, the overhead is really small. When I rolled out this implementation in an application serving millions of requests a day, there was zero measurable impact on performance. Even if the overhead was noticeable, it would still be worthwhile to pay the cost for most threat models.

It is conceivable that an application using the caching client might make a different cost/benefit calculation and decide that performance is paramount and key:value integrity failures are acceptable. That's why one approach I proposed was making it a configuration option in the upstream PR. Unfortunately the maintainer did not agree that the client should solve this problem at all, despite multiple other reports of it happening in production systems.

The maintainer had some valid points — application layer timeouts in Ruby are dangerous, and if you're using them, extreme caution is warranted. Consider killing the process entirely after a timeout to prevent state corruption bugs like this one.

Nonetheless, I firmly believe that given the severity of this issue it is worthwhile for the client itself to prevent the worst impact from happening. I am also not convinced that timeouts are the only way for this bug to happen. See the get_multi issue or consider the possibility of a future code change introducing a connection handling bug.

Alternatives

Another way to solve the problem would be to keep the socket locked until the response is read. That way, a socket with an unread response would not be re-used by a subsequent operation. I'm not sure why Dalli doesn't already work this way, but currently it releases the lock after issuing the get command and re-acquires it before reading the response. I opened a second PR proposing to keep the lock on the socket for the entire get sequence, which was also rejected.

The safe_get implementation still has an advantage in that it works regardless of whether the socket is properly handled or even if memcached sends extraneous responses. That approach is publicly available and production tested. Please let me know if you have any questions or feedback about it!

Fully remote companies are better than hybrid

Jonathan Steel — Wed, 01 Feb 2023 18:44:42 +0000

I have worked in many different environments throughout my career. I have worked in the same building as my teammates and even for a company that had us all in the same room. I have also worked in hybrid environments with a mix of in office and remote employees. In the hybrid case, I was always onsite. I had never been on the other side, where I was remote and there were other people physically together. And in my five years working for Aha!, I have always been grateful to work for a fully remote company.

I knew I did not want to work in an office anymore and only truly discovered while working at Aha! how great a remote team can be.

Fully distributed

Frequent communication and collaboration are invaluable to every group at a company. As an engineering team lead, I know this doesn't come as naturally to some as it does to others. Engineering team members can be especially susceptible to losing contact with the rest of the team and company when they are in a hybrid situation.

When some people are in person and others are remote it is harder for everyone to succeed equally. Some teams may see the creative work, decision-making, and architecture being discussed without the remote engineer that will do the actual work. Those decisions are encoded in the form of features, tickets, or tasks that flow down to the engineer. If there is any confusion in the work assignments, it may be perceived as a communication error on the part of the remote engineer.

When everyone is remote, there are no communication barriers. We are all accustomed to jumping on a video call or sending a quick instant message.

Onsites

Twice a year, our entire company gets together in person for a week at a destination travel location that we call our company onsite. Everyone has an amazing time discussing the product roadmap, meeting with teammates, volunteering through our Aha! Cares program, and enjoying great meals together.

In June 2022, Aha! was able to host an in-person onsite for the first time in over two years. Due to everyone's different circumstances, not everyone was able to attend, including me. We have a truly exceptional team that coordinates these events to include everyone as much as possible — whether onsite or offsite. But I was worried what that might look like.

So what was it like? At Aha!, we go above and beyond with everything we do and this event was no exception. Everyone tried their hardest to make sure we felt included. We even had our own events that were just as memorable as those at the previous offsite.

But hybrid work events are just not the same. Sometimes it was hard to hear side conversations and the random comments thrown out in the audience that caused a ripple of laughter.

The positive takeaway from the experience was that it crystallized in my mind the idea that I never want to work for a hybrid company. I don't think hybrid environments can ever work without leaving some team members feeling left out.

This onsite (when I was offsite) had me feeling left out in a way that I didn't when we were all in person or all remote.

Some aspects of hybrid environments may improve over time. Technology, tools, and processes can always get better. As hybrid environments become more common, people may also become increasingly familiar and comfortable working with remote and colocated team members at the same time. Even with all those improvements, there is no way to include a remote employee in the random dinner a team might share together.

I am lucky that Aha! will always make a great effort to include each and every team member. And I now know for certain that hybrid will never be as good as fully remote or fully in-person. My teammates at Aha! are all so passionate and motivated to bring their best to work every day — 100% remote is what works for us. I am more excited than ever to work for a fully remote company and I am especially excited for our next company onsite.

Aha! is happy, healthy, and hiring. Join us!

We are challenged to do great work and have fun doing it. If you want to build lovable software with this talented and growing team, apply to an open role.

Building a composable query generator for GraphQL

Justin Weiss — Fri, 13 Jan 2023 18:15:56 +0000

In a lot of newer projects, we use our GraphQL API. This is the same API you use when you're building Aha! Develop extensions. GraphQL has given us a more consistent, more flexible, and often more efficient way to access the data inside an Aha! account.

GraphQL queries are just strings:

const query = `{
  feature(id: "DEMO-29") {
    id
    name
  }
}`;

const response = await fetch("/api/v2/graphql", {
  "headers": {
    "Content-Type": "application/json",
  },
  "method": "POST",
  "body": JSON.stringify({ query }),
});

Strings are easy to start with and work well for simple, mostly static queries. But what about something more complex? What if you wanted the name of the person assigned to each feature but not when you're looking at a list of your own features? What if only some teams used sprints and you didn't want sprint information if a team didn't use them? How could you easily make wildly customizable views and only fetch the data you needed for that specific view?

Simple interpolation is one option:

const sprintQuery = sprintsEnabled ? `{
  sprint {
    id
    name
    startDate
    duration
  }
}` : "";

const query = `{
  features {
    id
    name
    ${ sprintQuery }
  }
}`;

But this can quickly get out of hand. You need to know in advance how a query can be modified so you can be sure to leave room for strings to be interpolated inside of them. Handling optional arguments can be a pain. So if strings aren't the right option for very dynamic queries, what is?

The next step beyond strings

There's a common solution to this problem: Store the information you need to make your final decisions in a more raw form that you can look at. Keep them in a structure — an introspectable form — until you're ready to generate a result.

What does that look like, though?

Say a part of your code wanted a few fields from a Feature API, "id", and "name". Some other code wants the reference number too. Instead of building a query as a string and interpolating fields into it, like this:

const query = `{
  features {
    id
    name
    ${ maybeReferenceNumber }
  }
}`;

You could keep a list of fields:

const fields = ["id", "name"];

Other parts of your system could add to it:

fields.push("referenceNumber");

And when you generate your query, the query has all of the information it needs right at hand:

const query = `{
  features {
    ${ fields.join("\n") }
  }
}`;

This seems like a minor change, and it is, but it's powerful. An object, which is easy to work with, keeps track of the decisions you've made up to this point. Your query generation is simple — it just does what the object tells it to do. Here, that's turning an array of names into fields in the query. This opens up a lot of possibilities but first we can clean it up.

How to store the query state

If you've ever used Rails, you'll know that it's great at building queries over time. You call methods to build up a query and only fire it off when you're done with it:

query = account.features
query = query.where(project_id: project.id) if project
query = query.where(release_id: release.id) if release
# ...

I've been surprised that more languages or frameworks haven't been influenced by this query building. To me, it's one of the best parts of Rails.

You can build something like this with GraphQL, though, keeping your decisions in an object and generating a query at the last minute. Imagine a Query class. We'll keep it simple to start, just holding a query type and a list of fields:

class Query {
  constructor(type) {
    this.type = type;
    this.fields = new Set();
  }
}

Next, you can implement a simple "select" method to select ID and name:

class Query {
  // ...
  select(fields) {
    fields.forEach(field => {
      this.fields.add(attr);
    });

    return this;
  }
}

let query = new Query("features");
query.select(["id", "name"]);

You can pass that query object around and other functions can add to that query object:

query.select(["referenceNumber"]);

Now, when you need it, the Query object can generate a query string. Just like the example above:

class Query {
  // ...
  toString() {
    return `{
      ${ this.type } {
        ${ Array.from(this.fields).join("\n") }
      }
    }`;
  }
}

Once you have this string, you can hand it to whichever GraphQL library you're using as if you wrote it yourself.

With that simple pattern, you can go further. You can add arguments to filter the results:

class Query {
  constructor(type) {
    // ...
    this.filters = {};
  }

  // ...
  where(filters = {}) {
    this.filters = { ...this.filters, ...filters };
    return this;
  }

  processFilters(filters) {
    // Very basic conversion, can be improved as necessary
    return Object.keys(filters)
      .map(k => `${k}: ${JSON.stringify(filters[k])}`)
      .join(', ');
  }

  toString() {
    let args = '';
    if (Object.keys(this.filters).length > 0) {
      args = `(filters: {${this.processFilters(this.filters)}})`;
    }

    return `{
      ${ this.type }${ args } {
        ${ Array.from(this.fields).join("\n") }
      }
    }`;
  }
}

let query = new Query("features");
query.select(["id", "name"]).where({ assigneeId: "12345" }).toString();

You can add subqueries to select information from child objects:

class Query {
  constructor(type) {
    // ...
    this.subqueries = [];
  }

  // ...
  merge(subquery) {
    this.subqueries.push(subquery);
    return this;
  }

  toString(options = {}) {
    const { asSubquery } = options;

    let args = '';
    if (Object.keys(this.filters).length > 0) {
      args = `(filters: {${this.processFilters(this.filters)}})`;
    }

    const subqueryString = `${this.type}${args} {
        ${Array.from(this.fields).join('\n')}
        ${this.subqueries.map(s => s.toString({ asSubquery: true })).join('\n')}
      }`;

    if (asSubquery) {
      return subqueryString;
    } else {
      return `{
        ${subqueryString}
      }`;
    }
  }}

And now you can build arbitrarily complicated queries based on whatever state you have:

let query = new Query('features');
query.select(['id', 'name']).where({ assigneeId: '12345' });

if (projectId) {
  query.where({ projectId });
}

if (includeRequirements) {
  let requirementsQuery = new Query('requirements');
  requirementsQuery.select(['id', 'name', 'position']);

  query.merge(requirementsQuery);
}

query.toString();

From now on, any time you want to change a query based on information you have someplace else, it's as easy as calling a method.

What's next?

This query generator is simple and is still missing a lot, but the core idea is easy to extend to fit your API:

You can add functionality for sorting, passing query arguments, pagination, etc.
You can have it generate GraphQL fragments and variables instead of a single string.
You can add another layer. For example, have your query framework generate Apollo documents instead of strings and you can get better editor integration and error messages.
You can create a mutation builder, tracking changes you make to your JavaScript objects and generating mutations based on those changes.

We've done all of those things, and found a lot of value in a flexible generator like this. Building a query generator ourselves also allowed us to integrate it more closely with other parts of our application framework. It's a nice simple base we could build off of easily.

And once you have this base — an introspectable object that can generate the strings you need — your code no longer needs to worry about the actual queries. It's just responsible for the decision-making and the generator does the rest.

Aha! is happy, healthy, and hiring. Join us!

We are challenged to do great work and have fun doing it. If you want to build lovable software with this talented and growing team, apply to an open role.

Using Capybara to test responsive code

Will Lawrence — Fri, 11 Nov 2022 20:41:21 +0000

As more users opt for mobile browsing, responsive design becomes more important — even for applications that are primarily used on a desktop. Responsive design is a key consideration for Aha! Ideas because it's convenient to answer polls and submit ideas using mobile devices. Usually the application behavior between mobile and desktop are the same, just rearranged on the page. But what happens when application behavior is different between devices with different-sized screens? Automated tests are necessary to ensure these different screen behaviors perform as expected in their environments.

Engineering at Aha! focuses on using and improving the Capybara test framework. We have added many helpers and additional functionality to make working with Capybara easy. Testing at mobile widths is another chance to improve our testing tooling. Here is the incremental approach that we used to add mobile testing helpers.

First pass

Below, we have an example test.

context "mobile user" do
  scenario "user logs in on mobile" do
    # These labels are specific to mobile widths
    expect(page).to have_content("First name")
    expect(page).to have_content("Last name")
  end
end

This test will fail because we aren't resizing to mobile width, so our name labels won't appear. Let's fix that.

context "mobile user" do
  # resize to mobile width
  before { page.driver.browser.manage.window.resize_to(375, 764) }

  scenario "user logs in on mobile" do
    # These labels are specific to mobile widths
    expect(page).to have_content("First name")
    expect(page).to have_content("Last name")
  end
end

This is an acceptable first pass. Our page is indeed resized for mobile testing. However, it presents three problems:

It doesn't tell us why we are resizing. The test has that information but it would not be clear out of the test.
This code isn't particularly reusable because it requires some insight into how Capybara works.
The test window remains resized for all subsequent tests. This is a subtle problem that will lead to unexpected and intermittent test failures.

Using a helper

Let's see how we can fix those three problems. Below is a helper we can use to resize for mobile testing.

# in spec/support/capybara_helpers.rb
def with_mobile_width
  page.driver.browser.manage.window.resize_to(375, 764) # resize to mobile
  yield # run the test
  page.driver.browser.manage.window.resize_to(1920, 1080) # resize back to default
end

And then in our test:

context "mobile user" do
  scenario "user logs in on mobile" do
    with_mobile_width do
       # These labels are specific to mobile widths
       expect(page).to have_content("First name")
       expect(page).to have_content("Last name")
    end
  end
end

This solution works better. It can be reused, it tells us why we are resizing, and it won't interfere with other tests. But there is still room for improvement.

We are adding another layering of nesting to the test. If we continue to use it in other places, then we are going to have some deeply nested tests. There is another way we can get this functionality without using this helper.

Updating our configuration

I want to be able to drop a :mobile_width in our test declaration. This resolves our three problems and won't clutter the tests. Below is an update to our configuration.

# in spec/support/capybara.rb
rspec_config.before(:each) do |example|
  browser = Capybara.current_session.driver.browser

  # if we have :mobile in test, resize. Otherwise go to default.
  if example.metadata.key?(:mobile_width)
    browser.manage.window.resize_to(375, 764)
  else
    browser.manage.window.resize_to(1920, 1080)
  end
end

Here we are using the before(:each) hook. This does exactly what it says on the box. Before each test runs, hook into it and perform an action. In this case, we are checking to see if the test has a :mobile_width key. If it does, run at a mobile width. If it does not, run at the standard width. The test looks a lot cleaner.

context "mobile user", :mobile_width do
  scenario "user logs in on mobile" do
    # These labels are specific to mobile widths
    expect(page).to have_content("First name")
    expect(page).to have_content("Last name")
  end
end

All the tests in the mobile user context are now going to run at that width. We have addressed the original three issues. This is reusable, it explains what we are doing to the test, and the mobile width won't leak into other tests. We also don't need to add another layer of testing to our code like we did by adding the with_mobile_width helper, so the tests remain tidy and sustainable.

Aha! is happy, healthy, and hiring. Join us!

This feature took a lot of tinkering and guidance from other engineers. Without such a knowledgeable and helpful team, I would not have arrived at this clean solution. If you want to build lovable software with this talented and growing team, apply to an open role.

Writing and testing a custom RuboCop cop

Kyle d'Oliveira — Fri, 21 Oct 2022 17:36:44 +0000

Solving a problem is great — but keeping it from coming back is even better. As we resolve issues in our code base, we often consider how to keep that classification of issue out of the code base entirely. Sometimes we reach for RuboCop to help us police certain patterns. This also helps to document the originating issue and educates teammates on why these patterns are undesirable.

RuboCop is more than just a linter. It is highly extensible and allows you to write custom cops to enforce specific behavior. These cops can be used to create better code practices, prevent bad patterns from sneaking into a legacy code base, and provide training for other engineers. But it can be tricky to know how to create a new cop and if it will work long-term.

We can write unit tests to ensure the success of our custom cops, just as we would with any application code.
Let's explore this with an example to show how testing could be done.

Testing custom cops

With the Aha! engineering team, every model has an account_id attribute present and for security reasons, we never want this to be set via mass-assignment. To avoid this, we want to prevent certain attributes from being added to attr_accessible.

# bad
class Foo
  attr_accessible :name, :account_id
end
Foo.create(account_id: 1, name: "foo")
# good
class Foo
  attr_accessible :name
end
foo = Foo.new(name: "foo")
foo.account_id = 1
foo.save

We have a custom cop that analyzes the arguments to that method and will error if any protected attribute is present. The custom cop we have ends up looking something like this:

class RuboCop::Cop::ProtectedAttrAccessibleFields < RuboCop::Cop::Cop
  # We can define a list of attributes we want to protect
  PROTECTED_ATTRIBUTES = [
    :account_id,
  ].freeze
  # We can define an error message that is displayed when an offense is detected.
  # This can be helpful to communicate information back to other engineers
  ERROR_MESSAGE = <<~ERROR.freeze
    Only permit attributes that are safe to be completely user controlled. Typically any *_id field could be problematic.
    Instead perform direct assignment of the field after doing a scoped lookup. This is the safest way to handle user input.
    Some fields such as #{PROTECTED_ATTRIBUTES.inspect} should never be used as part of attr_accessible.
  ERROR
  # We want to examine method calls. Particularly those that are calling the attr_accessible method
  # and also have arguments we care about
  def on_send(node)
    if receiver_attr_accessible?(node) && protected_arguments?(node)
      # If we do detect an attr_accessible call with arguments we care about, we can record an offense
      add_offense(node, message: ERROR_MESSAGE)
    end
  end
  private
  def receiver_attr_accessible?(node)
    node.method_name == :attr_accessible
  end
  def protected_arguments?(node)
    node.arguments.any? do |argument|
      if argument.sym_type? || argument.str_type?
        PROTECTED_ATTRIBUTES.include?(argument.value.to_sym)
      end
    end
  end
end

This custom cop does the trick. Adding a test for it ensures that it won't break in the future when we update RuboCop or extend the functionality. In order to write a test, we need to understand how the custom cops are set up and run.

Instantiate a custom cop

RuboCop::Cop::Cop inherits from RuboCop::Cop::Base and that allows the instantiation without any arguments. So it turns out this isn't anything special — creating a new instance of our cop is really as simple as: RuboCop::Cop::ProtectedAttrAccessibleFields.new

If the cop requires some kind of configuration, it can be passed to the instance via a RuboCop::Config object. The RuboCop::Config takes two arguments. RuboCop can provide configuration via YML files. You can use the first argument of RuboCop::Config to pass this configuration with various values from the test. The second argument is the path of the loaded YML file, which can be ignored in the tests.

config = RuboCop::Config.new({ RuboCop::Cop::ProtectedAttrAccessibleFields.badge.to_s => {} }, "/")
cop = RuboCop::Cop::ProtectedAttrAccessibleFields.new(config)

Process, execute, examine

As it turns out, there is a method available, RuboCop::Cop::Base#parse , that accepts a string as input and will return something the cop can process.

This allows us to have something like:

source = <<~CODE
  attr_accessible :account_id
CODE
processed_source = cop.parse(source)

There is a class from within RuboCop, RuboCop::Cop::Commissioner , that is responsible for taking a list of cops and using those to investigate the processed source code. In order to run our cop, we can run this method.

commissioner = RuboCop::Cop::Commissioner.new([cop])
investigation_report = commissioner.investigate(processed_source)

The RuboCop::Cop::Commissioner#investigate method will return an instance of RuboCop::Cop::Commissioner::InvestigationReport which is a simple struct class that has a list of offenses that have been recorded.

Put it all together

We end up with a test file that looks something like this:

describe RuboCop::Cop::ProtectedAttrAccessibleFields do
  let(:config) { RuboCop::Config.new({ described_class.badge.to_s => {} }, "/") }
  let(:cop) { described_class.new(config) }
  let(:commissioner) { RuboCop::Cop::Commissioner.new([cop]) }
  it "records an offense if we use allow account_id as a string" do
    source = <<~CODE
      attr_accessible :foo, 'account_id'
    CODE
    investigation_report = commissioner.investigate(cop.parse(source))
    expect(investigation_report.offenses).to_not be_blank
    expect(investigation_report.offenses.first.message).to eql described_class::ERROR_MESSAGE
  end
  it "records an offense if we use allow account_id as symbol" do
    source = <<~CODE
      attr_accessible :foo, :account_id
    CODE
    investigation_report = commissioner.investigate(cop.parse(source))
    expect(investigation_report.offenses).to_not be_blank
    expect(investigation_report.offenses.first.message).to eql described_class::ERROR_MESSAGE
  end
  it "doesn't record an offense if no protected attribute is used" do
    source = <<~CODE
      attr_accessible :foo
    CODE
    investigation_report = commissioner.investigate(cop.parse(source))
    expect(investigation_report.offenses).to be_blank
  end
end

Now that we know how to write tests, we can use them as a starting point for building new cops, extending existing cops, and ensuring that things continue to function as our application grows and evolves. These little investments into project-specific cops can end up being a large investment in the future health of the projects.

Sign up for a free trial of Aha! Develop

Aha! Develop is a fully extendable agile development tool. Prioritize the backlog, estimate work, and plan sprints. If you are interested in an integrated product development approach, use Aha! Roadmaps and Aha! Develop together. Sign up for a free 30-day trial or join a live demo to see why more than 5,000 companies trust our software to build lovable products and be happy doing it.

Service layer for business logic — Organizing code in a Rails monolith

Jonathan Steel — Fri, 14 Oct 2022 19:10:30 +0000

Our engineering team builds the Aha! suite using a Rails monolith. We carefully weighed a number of options before determining that this would provide the most lovable solution for our users and our team. But the discussion does not end with choosing this path for our code.

We work hard to build the best monolith possible so we can retain a high velocity and a clean code base.

One of the foundations of having a successful monolith is to ensure it is well-organized. Having a service layer for business logic can help keep Ruby on Rails code from growing out of control. Whichever framework you use, it will only help organize the common elements. Design a system for organizing your business logic code using well-defined, unambiguous patterns. Read on to learn how we did this for the Aha! suite.

Managing business logic

Rails does a great job of giving you a place to put just about any kind of code. When you create a new Rails project, it comes with an elegant predefined directory structure. There is a place for the models, views, controllers, tests, assets, database migrations, and much more. It does have its limitations though. The most common issue that Rails projects run into is how to deal with business logic.

When you look at tutorials of Rails code, they are usually beautiful, concise, simple, and easy to read. Many real-life projects start out this way as well. But over time, more and more business logic gets peppered into that clean, elegant code. You cannot avoid this business logic because you would not have a program without it. So as your Rails program grows and ages, all these clean areas of code will start to grow and look less and less like the ideal "Hello, world" examples. The question then quickly arises of where this code should go.

Often this complex business logic will start to collect in the controllers. A very common practice is to push that logic into the models in an attempt to keep the complexity in one spot. The size of your models is going to grow proportionally with the size of your application. Combining all your complicated and most frequently used logic together into a single location that never stops growing is a disaster waiting to happen. This will start to get painful as your application becomes a monolith and the code becomes unreadable.

Does Rails have a place for business logic? The Rails guides mention the lib directory as a place for extended modules for your application. You'll find some examples of pushing complex code into concerns, but most concerns are for code reuse. That code is still being included in the same places we said not to put the business logic.

Never force code into a framework if there is no clear place for it — you may have to venture off the Rails instead.

Business logic attracts complexity and tends to change more frequently than other areas of your code. This creates the perfect breeding ground for bugs and regressions. Any solution should isolate the business logic, making it easier to test and accelerate future changes. When file size increases proportionally with the application size, your code is destined to be hard to read, understand, and modify. The best way to prevent this is to create code that is narrowly focused instead of serving multiple purposes.

Creating a service layer

One concrete solution is to create a service layer composed of small objects that serve specific use cases. A service layer for business logic can help keep Ruby on Rails code from growing out of control. Whether you use Ruby on Rails or another language and framework, that framework will only help organize common elements. Take a cue from your framework and design a system for organizing your business logic code using well-defined, unambiguous patterns.

A common place to create a service later is in app/services. Each object will usually only serve a single purpose or possibly a few very tightly related purposes. Keeping these objects focused and constrained to a single purpose ensures that no matter how complex your monolith gets, these objects will never get too big. Here is an example of a simple service:

class ScheduledReportRunner
  def send_scheduled_report(scheduled_report)
    return unless allowed_to_send_report?(scheduled_report)

    reply_to = calculate_reply_to(scheduled_report)
    ScheduledReportMailer.scheduled_report_message(scheduled_report, reply_to).deliver.now

    scheduled_report.next_run += scheduled_report.send_frequency.days
    scheduled_report.save!
  end

  private

  def allowed_to_send_report?(scheduled_report)
    ...
  end

  def calculate_reply_to(scheduled_report)
    ...
  end
end

This class is small and easy to understand, use, and test.

describe ScheduledReportRunner do
  describe "#send_scheduled_report"
    it "delivers a scheduled report mail message"
      scheduled_report = create(:scheduled_report)
      expect(ScheduledReportMailer).to receive(:scheduled_report_message).with(scheduled_report, "support@aha.io").and_call_original
      described_class.new.send_scheduled_report(scheduled_report)
    end

    it "does not send a report that is not allowed to go out"
      scheduled_report = create(:scheduled_report, last_sent_at: 5.minutes.ago)
      expect(ScheduledReportMailer).to_not receive(:scheduled_report_message)
      described_class.new.send_scheduled_report(scheduled_report)
    end

    it "schedules the next run of the report"
      scheduled_report = create(:scheduled_report, send_frequency: 10.days)
      described_class.new.send_scheduled_report(scheduled_report)
      expect(scheduled_report.next_run).to be > 9.days.from_now
    end

    it "uses a custom reply_to when necessary"
      scheduled_report = create(:scheduled_report, last_sent_at: 5.minutes.ago, reply_to: "fred@aha.io")
      expect(ScheduledReportMailer).to receive(:scheduled_report_message).with(scheduled_report, "fred@aha.io").and_call_original
      described_class.new.send_scheduled_report(scheduled_report)
    end
  end
end

It is often useful to return rich domain objects specific to that service object. For example, instead of returning a single value, you can return an object that has a status, error codes, and multiple model objects. That object can then be passed around as a single unit that shows the correlation between the various items inside it.

Organizing with a service layer

In a controller, you can wrap all related business logic together into a single object, take the return value, and pass that on to your views. The rich return objects often eliminate the need to have multiple instance variables instantiated and drilled down through your views. Helper code can now be stored in a more appropriate place that is usable by parts of the code other than views.

Jobs and rake tasks often end up getting pretty complex as well. These should be very thin wrappers that parse arguments and then delegate to a service object. Structuring your code in this way makes it easy to call from the console if somebody wants to run a rake task or job manually. Having small classes also helps immensely with testing a monolith. By simplifying other areas of your application like models, controllers, and jobs, they now become much easier to test as well.

The service layer also provides isolation from the rest of your Rails code. Isolation is desirable to provide room for experimentation. You can use whatever coding style you want to create these objects without enforcing that structure on other parts of the code. You can use plain old Ruby objects, classic object-oriented inheritance hierarchies, object composition, meta programming, or even some esoteric bash script you wrote years ago. I prefer small and simple plain old Ruby objects, which are easy to follow.

It also does not matter how you organize files within the service layer, especially at first. As your service layer grows, patterns will emerge and you can reorganize by creating subdirectories and moving files around. But no matter how big or organized this code gets, you can always create a new subdirectory and try out a new experimental approach there.

Shipping a Minimum Lovable Product

Using a service layer helps us to align our work with our team and company goals. We always strive for the Minimum Lovable Product (MLP), only shipping features when they are ready from a technical standpoint. An MLP is an initial offering that users love from the start. It should also be loved by the engineers that are working to maintain it.

Features cannot just look good on the frontend — they should be well-organized in the background as well.

The service layer helps you ship strong code the first time. When you are first authoring a feature, it is very simple to take a chunk of code and create a service object out of it. This means you are more likely to do that right from the start instead of waiting to refactor at a later date. If you do need to refactor, it will mean shuffling around code in small isolated objects and files. That is much easier than coming back after your feature is ready and trying to collect up all the logic you sprinkled around in models, controllers, and views. The service layer is so easy to use that you will feel guilty pushing up a pull request with code where it should not be.

If used properly, the service layer will help keep your Rails code looking like the simple examples of the Rails guides. It helps to avoid technical debt and allows Rails to accomplish what it was built for. It also helps reduce the complexity of implementing, maintaining, and testing business logic. It will help you deliver great features with your growing monolith and keep you happing while doing it.

We will continue to evolve our monolith and make alterations to the architecture to meet our growing needs. Read our other posts on how we chose to utilize a monolith for the Aha! suite:

From One, Many — Building a Product Suite With a Monolith

Embrace the monolith: Adding a new product to Aha!

Sign up for a free trial of Aha! Develop

Platform Engineering vs. Site Reliability Engineering

Alexander Bartlow — Wed, 28 Sep 2022 17:33:52 +0000

Striker and goalie. Offense and defense. Deploy and recalibrate. Many disciplines have dichotomy between the tasks that accomplish a goal and tasks that protect the ability to do so. Delivering features, building out user flows, and optimizing conversion rates constitute the "offense" of many software companies. All of these activities are directly tied to the goal of growing the business. Defensive tasks encompass security, operations, and disaster recovery. These tasks are designed to prevent loss and empower the offense.

An engineering team cannot run optimal code or move the business forward with a weak infrastructure.

In the software world, this alliance is realized through the engineering and operations teams. Some organizations refer to these as the "profit-center" and "cost-center," respectively.

Traditional site reliability engineering

Though symbiotic, the relationship between engineering and operations may encounter pitfalls at more complex organizations. The introduction to Google's Site Reliability Engineering: How Google Runs Production Systems describes how the two groups may have varied goals, backgrounds, skill sets, incentives, vocabulary, and assumptions. And when left unchecked, strife can form as organizational effectiveness breaks down.

Google's solution to this problem is the discipline of site reliability engineering (SRE). Developers are tasked with writing software that creates a stable environment for the deployment and operation of the infrastructure. Site reliability engineers at Google work with development teams on a sort of contract — SRE runs the application only if development follows the practices needed to make the application run efficiently. If the development team does not hold up their end of the bargain, then the SRE will decline to hold up theirs and work with teams who do.

This works well for Google, but turning down work from one part of our engineering team is not an option for the Aha! team. We have no site reliability engineers on staff at Aha! — because we found a better way.

Unified engineering goals

We solved the problem of the development-operations split by defining clear goals for our dedicated platform team. Our platform team has goals similar to a traditional operations team, such as:

Operability — How do we run the system on a day-to-day basis and make routine changes?
Reliability — How do we ensure the system is available for our customers?
Resilience — When the system is unavailable, how do we get it running again?
Observability — How do we ensure that we know before our customers when the system needs help?

We have also adopted six additional goals to help us create a happy, effective, and high-performing engineering team:

Inverse toil

Toil refers to the time engineers spend doing repetitive work that doesn't deliver real value to customers. While the amount of manual work the platform team needs to do to operate production is higher than the rest of the engineering team, we still try to keep our time spent toiling to a minimum. For most of our platform engineers, it's less than 20% of their time. Google's SREs target 50% or less time spent toiling, so we believe that our investments in automation have been very effective.

Release velocity

How long does it take a pull request to be deployed after being flagged as ready? While we attempt to optimize the time taken in continuous integration, test automation is not a core focus for us. Our developers closest to the code are best suited to test it, so we leave that responsibility to them. We instead focus on the deployment pipeline — building the core images and getting them into production. Simplifying that process allows it to be done many times a day.

Change management

In addition to deployment speed, some changes require a gradual rollout or an experimental stage to validate the changes we made. The platform team manages the feature flag functionality at Aha! and continues to extend it to provide support for more use cases.

Developer productivity

The platform team maintains a robust logging system to allow our engineers to troubleshoot problems in production quickly and effectively without direct access to customer data. We maintain the Docker setup for local development to give engineers a stable way to run the application and all of its dependencies. Our dynamic staging setup allows us to get new features in front of the product, marketing, and Customer Success teams early in the development process.

Application performance

All engineers should attempt to create a performant application. Our focus on monitoring and observability allows us to find problems in production and start the troubleshooting process. Some features may need to go back into development for optimization, but we can often solve the problem through algorithmic tweaks, indexing changes, or other database management techniques. Our experience looking into these issues gives us a sense of where additional caching, reducing object allocations, or other techniques could be used to bolster end-user performance.

These goals and techniques are also shared by the DevOps movement, which attempts to push all the operations work back onto the engineering team. However, developing a large monolithic Rails application with a robust and modern front-end framework encompasses two very deep skill sets. Asking all of our engineers to also be AWS, networking, and database engineers is asking far too much.

Our platform team serves and empowers the rest of the engineering organization. All of our goals unite to serve the company vision.

Making complicated problems simple

Without new features to uncover what is currently possible with our infrastructure, we wouldn't be able to solve complex problems. Part of that empowerment entails building out all-new infrastructure and paradigms that can be used to solve tomorrow's problems. We've made a massive effort toward integrating Kafka into our infrastructure this year, which is typical of this kind of investment. By having some space away from product-facing work, we're able to think of our product engineers as internal customers. We can build out tools and infrastructure that will support the development of future features and products.

Platform for profit

Remember the profit-center vs. cost-center distinction? New development generally gets billed as profit-generating, but the operations side of an organization has the unique ability to drive costs down. This is done through fine-tuning the spend on Cloud resources, optimizing execution to require less of those resources in the first place, and selecting time-saving technologies.

Infrastructure budget is a vital component of the technical roadmap for any platform team. When the development team is bottlenecked for infrastructure reasons, the organization loses out on critical first-mover advantages in the marketplace.

Poor engineering practices can lead to a deficit of our most important asset — the team.

We want our teammates to love what they do — increasing employee joy is the aim and core of our company's existence. And it makes financial sense too. Replacing an engineer's institutional knowledge and expertise takes time. Attrition makes your hiring plan doubly difficult to achieve.

Need for speed

Focusing on optimization allows platform engineers to improve the company's service in noticeable ways. Speed is a feature because performance expectations are similar to the delays we expect in a normal conversation. A response of 100ms feels instantaneous but delays longer than one second start to interrupt the user's flow of thought. Beyond four seconds, the user can no longer smoothly interact with a system.

Products in your daily workflow should be reliable and resilient — these two factors drive the happy use of software.

Failures can occur through human error, hardware malfunction, or bugs in vendor packages. However, my experience has shown that a system that recovers quickly when it fails is viewed more favorably than one that fails infrequently but has a longer recovery time.

A system in this case may refer not only to your software and hardware, but also your operations, engineers, and customer success teams. When failures are still within the realm of exceptional behavior and are fixed rapidly, we find those customer interactions are generally positive — even lovable. Customers who love your product will keep using it (reducing churn, increasing profit) and expand the use of the product within their own organization. Platform teams support the broader engineering organization by being prepared to respond quickly to the most debilitating failure modes. This is a core overlap with SRE teams as well.

Structuring engineering teams

If SRE teams are the defense and engineers are the offense, then platform teams are the mid-fielders. They save goals as often as they score them. Their presence makes the rest of the engineering organization more effective at their core objectives.

However, keep in mind the time spent toiling. If the platform, infrastructure, QA, and tooling engineers spend over half of their time responding directly to incidents or on-call work, you may need a dedicated reliability team.

If every week has a new emergent behavior that requires platform engineers to drop everything and fix it, it's time to adopt more proactive measures to build resilience, monitoring, and fault-tolerance. And when those tasks take up more than half the platform team's time, it's time to honor reality and break off a dedicated reliability engineering team.

Platform and SRE teams do much of the same work — the division between them is more like a gradient than a clear line:

When the platform team is fully aligned with engineering and company goals, it can incorporate a healthy SRE culture that meets its needs. Focusing on observability, recovery, and reliability saves costs and increases reliability while the platform team works on enhancing the developer experience and building new infrastructure for future features or projects.

Grow your career and be happy

If this kind of alignment and environment sounds intriguing to you, come join us and work with the sharpest engineers I've ever had the pleasure of calling colleagues. Career happiness comes from doing meaningful work with motivated teammates and being appreciated for it. That is Aha! — a talented group of people changing how the best-known companies innovate and bring products to market.

Technical debt isn't technically debt

Jeremy Wells — Wed, 07 Sep 2022 23:40:58 +0000

The term "technical debt" has entered the standard lexicon of programming and software project development and has often been called out for being an incorrect metaphor. Yet it persists as a way to talk about the decisions made during software engineering. I believe it is over-used and often makes technical conversations more confusing.

Our team at Aha! has meaningful conversations about the trade-offs of software development without using the term "technical debt."

There are two common ways the term "technical debt" is used now. The first is when engineers are talking with someone who doesn't have the same technical context of a project. In this case, it may be used to smooth over the difficulty of communicating various ideas. Those ideas are typically:

We can deliver feature 1 faster but that means feature 2 will take longer.
This feature is going to take longer because of how we approached earlier features. You can see that those are conceptually similar other than the timing. The message is that the developer needs more time to work on these features. Calling it technical debt avoids the need to explain the finer details. You might also say:
We’ve incurred technical debt so we need to clean that up before planning the next features.

This communicates that engineering is not happy with the code as it stands. We would like to work on it without needing to worry about delivering functional changes. The term is again used to avoid further explanation and scrutiny. It has entered the mindset of many people in software development that "technical debt" is something that just happens and needs repaying.

The other common usage is between engineers as justification for making certain decisions or for why the code is the way it is. Many times it sounds like an excuse. If an engineer is embarrassed about the state of the code or architecture, they may call it technical debt to signal to other engineers that the problems arose due to external factors.

I’ll address the problems with these usages, but first let’s consider what technical debt should actually mean.

What is technical debt

Let's remove all the built-up subjective meaning that has crept into the term "technical debt." Similar to monetary debt, it is a balance between having what you need now and the total costs plus risk. That balance plays on our tendency to want results right now and to play down the long-term consequences. Consider the technical debt thought process:

You need to deliver a feature.

Option A: Deliver the current feature as fast as possible. Your subsequent features may take longer due to more necessary patchwork.
Option B: Take time to build a maintainable solution for the current feature. Your subsequent features may require less heavy lifting.

Which do you choose?

Not technically debt

I believe "debt" is simply the wrong way to describe this process. With monetary debt, your choice is clear and defensible: I need this money right now or I don’t. Ideally, the loan terms and outcomes are presented upfront.

This technical choice is not so cut and dry. Is Option B better? How can we be sure that investing extra time now will pay off later? For financial assets, calculating risk is a well-established process. Software development isn't as predictable. Future product and business decisions may alter your plans altogether. A shifting roadmap may waste your big investment.

Feasibility also plays a part. Software is built in layers — some of which we don't control. Architectural concepts emerge over time and change to meet the needs of the system. Is this choice apparent and real? Is the engineer working on the problem in a position to choose? I’ve been down enough dead-ends and thought experiments to say that often an apparent choice is a false one. Those experiments might inform later changes but that does not make the current implementation a debt.

Managing uncertainty

Option A may slow down your subsequent features, but it may not. You may have truly found a faster solution. Option B may save you hassle in the long run, or it may not. Your time spent upfront may be wasted if the roadmap changes drastically.

With all of the issues around estimating software projects, it is impossible to predict with certainty. The next feature might not be developed, the requirements might change. Traditional debt has fewer surprises. You don’t take out a loan on a car, discover it was a boat and find out you actually need to take it skiing.

Consider this choice instead:

You have one feature that you will deliver first and one follow-up feature.

Option A: Deliver the first feature faster with non-ideal code or technical choices to make the second feature easier.
Option B: Take longer to deliver the first feature and perform less rework for the second.

With either option, you haven't created a debt. You've simply made decisions about the timeline. This is called planning and all good plans take some finessing.

When relaying updates to cross-functional teammates, simply explain the problems and give realistic timelines based on what needs to happen. Blaming a delay on technical debt only hinders transparency and keeps your teammates in the dark.

With your development team, technical debt should not be an excuse to hide behind. Decisions are made, mistakes happen, external forces are at work. Discuss what happened and determine your next steps. Your project cannot be bankrupt by technical debt.

Investing time

Rarely do we have all the time we need to make our code perfect. But that's okay. You may have heard that "Premature optimization is the root of all evil in programming," from Donald E Knuth. Certain ideas about code and software are worth tempering — such as making code flexible or thinking about inflection points. But too much can lead to premature optimizations, over-abstractions, and needless configuration. The code itself is easy to change. If you don’t need a reusable abstraction now, add one later.

You've probably heard the saying, "Don't Repeat Yourself (DRY)" — and how applying that too early or aggressively can also introduce friction. Remember these rules of two and three.

For small code, use the rule of three:

I’m implementing this for the third time — I should introduce a generic way to handle this pattern.

Why three? Because you copied and pasted the first solution and made changes. On the third go, you understand the changes and are ready to solve it differently.

For larger concepts, use the rule of two:

I made this model and it worked well, but now I want to use it again and it doesn’t quite fit. I should restructure this to be useful.

You’ll want to reuse the concepts that drive other parts of the codebase. They might not be in a good state for reuse, so now is the time to analyze and create layers and abstractions.

The fact that you didn’t do that before is not technical debt. This is software development.

We work fast at Aha! and we use our products to build our products. Our team is happy, productive, and hiring — join us!

DEV Community: Aha!

Building a dynamic Canvas rendering engine using JSX

The challenge

Dynamic content

The naive solution

Buttons

JSX

The solution

Introducing CanvaSX

How does it work?

A parting note

Ruby enumerables considered helpful

Automatic pagination

Save a block for later

CLI tools at Aha!

Take your command-line utilities to the next level with these Ruby gems

I love creating command-line utilities

1. cli-ui

2. terminal-table

3. ombre

12 Tools for Quality Pull Requests

What is a quality pull request?

Tools for writing pull requests

#Cheat Sheet

On Writing

Using Details Tags

Adding Footnotes

On Structural Artifacts

On Responding

Going deeper

Do I have all the right reviewers?

Do reviewers have all the information they need?

Is my information organized in descending levels of scale?

Will someone looking at this in the future be able to access the "what" and "why" behind the "how" of this implementation?

Can I represent this detail with a comment?

Can I hide nonessential information using <details> ?

Is there supplementary information I could add as footnotes?

Should I include some kind of diagram, illustration, or screenshot?

Can I clarify my title for other contexts?

Tools for responding to pull requests

Could this be phrased as a question or observation?

Does my feedback block approval?

Is this a nit?

Does my review include something I like?

Choose tools to support your purpose

Solving a critical bug in the default Rails caching library

An odd coincidence

The bug mechanism

How it happens

The fix

Analyzing the fix

Alternatives

Fully remote companies are better than hybrid

Fully distributed

Onsites

Building a composable query generator for GraphQL

The next step beyond strings

How to store the query state

What's next?

Using Capybara to test responsive code

First pass

Using a helper

Updating our configuration

Aha! is happy, healthy, and hiring. Join us!

Writing and testing a custom RuboCop cop

Testing custom cops

Instantiate a custom cop

Process, execute, examine

Put it all together

Service layer for business logic — Organizing code in a Rails monolith

Managing business logic

Creating a service layer

Organizing with a service layer

Shipping a Minimum Lovable Product

Platform Engineering vs. Site Reliability Engineering

Traditional site reliability engineering

Unified engineering goals

Platform for profit

Need for speed

Structuring engineering teams

1. `cli-ui`

2. `terminal-table`

3. `ombre`

Can I hide nonessential information using `<details>` ?