There are many online resources about coding or finding a job in the tech sector. This post is not one of those. It is focused on soft skills, which I think a junior developer should have.

Your biggest goal is to learn and grow. Most habits you pick up in the early days of your career will stick.

• ✅ Be reliable

• 🤔 Be curious

• 💤 Work on boring tasks

• 🏆 Take ownership

• 🚫 Handling "No"

• 📖 Read “The Pragmatic Programer”

Subscribe now

Let's get started. 👉

✅ Be reliable

The first piece of advice I find highly important is reliability.

ALWAYS follow up on your task commitments.

Don't leave TODO comments in your code, fully complete your work. Leave your code better than you found it.

When you find that you can't finish a task on time, don't hide it. As soon as you think you can't deliver, ask for help.

You have to show that you are reliable. It is the most important thing to do.

Your teammates will quickly learn if they can count on you. The more people count on you, the more critical projects you are given.

🤔 Be curious

Be curious and ask questions. Don't be content with not understanding things. This is a nasty habit.

Try to review other people's pull requests. If you don't understand something, ask. Often, you aren't the only one who doesn't understand. If you are too shy to ask in public, ask directly via private chat message.

I love working with juniors who ask questions. They are good at spotting overly clever code tricks and unnecessary complexity.

One of the best ways to learn is by working with other people. Ask people if they want to pair program with you. I've learned a lot from pairing with other developers.

💤 Work on boring tasks

In your early days, you will work on many "boring" tasks like bug fixes or minor UI changes. You should try to find joy even in boring tasks.

Fixing small bugs will show you how systems are built and how to avoid writing them in the first place.

Once, I was tasked with keeping our application free of runtime exceptions. This was a very useful experience. It showed me how the system was breaking. I built many internal tools to handle errors and started designing my code to be more robust.

For small repetitive tasks, think about how to automate them or use them as training for your editor skills. I learned my Vim shortcuts by doing a lot of CSS fixes.

🏆 Take ownership

By ownership, I mean taking the initiative and actively participating in scoping and estimation, not just executing your tasks.

Try to be involved in time estimations -- often, you won't be consulted (this is a mistake on your team's part).

Don't rush to estimate. Take your time to think about the problem. Consult your team members.

A common mistake is to provide a time estimation that's as low as possible and then not deliver. Be honest and conservative.

...and no, doing an all-nighter to finish a task on time is not proper time planning.

Estimates are tricky; don't hide when you're behind. Embrace it, raise the issue, and look for help.

🚫 Handling "No"

You will be full of ideas, this is great. However, you will often be told "No".

"No" is essential in product development.

This can be quite painful. Don't get discouraged. Understand the reasoning behind the "No".

Sometimes the idea is just not right or has already been tried. Other times, "No" is "we don't have time right now" because of other priorities.

Show, don't tell. If you have an idea, implement it and make a demo. The ability to present your ideas well is a valuable skill.

Programmers tend to disagree a lot in abstract and agree when they see the working code.

When I tried to convince my team at Product Hunt to switch from a standard RESTful API to GraphQL, I didn't just say "Let's move to GraphQL."

Instead, I implemented a very complex page with GraphQL in a separate branch. I gave a presentation showing all the problems GraphQL would solve for us and presented a migration plan. I didn't hide any of the risks associated with GraphQL.

Again, don't get discouraged even if your prototype is rejected. Understand why it was rejected.

📖 Read “The Pragmatic Programmer”

I'd encourage you to read is The Pragmatic Programmer. I think every programmer should read it. I used to gift this book to every new engineering hire at Product Hunt.

Conclusion

Many of the habits and skills you build at this stage in your career will stick, so put extra care into nurturing the right habits.

To wrap it all up, I would like to recommend an excellent book that

On the technical side, master your editor and the programming language you are working with.

Last but not least, take care of yourself. Work hard but don't overwork. Get enough sleep every night.

You can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

In the era of evergreen browsers, we can use new HTML/CSS relatively early after their release.

In today’s post, I will walk through the use case in which you can use HTML/CSS instead of writing JavaScript.

• 📦 Store state in the URL

• 🖱️ Use CSS for hover effects

• 📱Use CSS for responsive UI

• 🗓️ Use a proper input type instead of a custom input

• 🔽 Use “details” HTML element

• 🖼️ Use “dialog” HTML element

Subscribe now

So, let's get started 👉

📦 Store state in the URL

This could be its own post; it is a pet peeve of mine. 😅

I have commented on too many pull requests about forms like the following, where the state is stored with the React.useState hook, when the best place for this data is the URL.

This way, you don’t lose your state when the page refreshes, you can send this URL to someone else, and the back button works.

Of course, it has its gotchas, like only updating the URL when the user stops typing in the search field, etc.

Even worse offenders are paginations or navigations, which are stored only locally, not reflecting which page the user is on.

🖱️Use CSS for hover effect

I have seen too much code like the following:

function MyButton() {
  const [isHovered, setIsHovered] = useState(false);

  const className = isHovered ? 'button button-hover' : 'button';
  const onMouseEnter = () => setIsHovered(true);
  const onMouseLeave = () => setIsHovered(false);

  return (
    <button 
      className={className} 
      onMouseEnter={onMouseEnter} 
      onMouseLeave={onMouseLeave}>Button</button>
  );
}

Simple CSS can replace this:

.button:hover {
   ...code
}

And the button becomes just:

<button class="button" />

With hover, you can do a lot of cool things. My previous post about Tips for Tailwind CSS showed how to use “group” and “group-hover:” to style children when their parent is hovered.

<div class="group">
   <span class="group-hover:bg-cloud">
     When parent element (group) is hovered, I change background
   </span>
   <span>
     I don't change color
   </span>
</div>

📱Use CSS for responsive UI

CSS media queries and the upcoming container queries are the way to design responsive UIs.

In Angry Building, we have a lot of tables. One could say most of our UI is tables. 🙈

On mobile, those tables become a list of cards. We use a regular HTML table, which changes its “display” style on smaller screens.

The way this works is that on mobile screen sizes:

1. table elements switch to display block/flex.

2. I use the CSS “content” attribute and “attr” function trick to get cell titles

Here is the simplified CSS for this.

@media (max-width: 640px) {
  .table-component,
  .table-component thead,
  .table-component tbody,
  .table-component tfoot,
  .table-component tr {
    display: block;
  }

  .table-component tbody td {
    display: flex;
  }

  .table-component tbody td:not(.actions):before {
    content: attr(title);
    flex: 0 1 35%;
    display: block;
    white-space: nowrap;
  }
}

🗓️ Use a proper input type instead of a custom input

The input element has many types available and is very well supported.

The one I have used constantly recently is the “date” type; it has a built-in calendar. 📅

I like using <input type=”date” />, instead of a JS calendar library because:

1️⃣ Accessible
2️⃣ Mobile friendly
3️⃣ All batteries included
🏆 No extra code

It's important to note that the “date” input type has limitations.. For instance, the popover calendar can't be styled to match a website and only allows for the selection of a single date.

There are many more useful types, like

• range

• color

• datetime-local

• month

• time

• week

• … and more

I can’t tell you how much JavaScript code I have added to various projects to handle dates. In one project, there were four different calendar libraries. 🤦‍♂️

🔽 Use “details” HTML element

The <details> disclosure element has been supported in all major browsers for years.

It allows you to have expandable/collapsible content.

No JavaScript, no CSS—just HTML:

<details>
  <summary>System Requirements</summary>
  <p>
    Requires a computer running an operating system. 
    The computer must have some memory and ideally some 
    kind of long-term storage.
  </p>
</details>

With a bit of CSS, you can create a mobile hamburger menu like the one we have at Angry Building.

The code for this menu looks like the following:

HTML

<details>
  <summary>
     <svg class="open-hidden">...</svg>
     <svg class="open-visible">...</svg>
  </summary>
  <ul>
    <li><a>...</a></li>
    <li><a>...</a></li>
    ...
  </ul>
</details>

CSS

details[open] .open-hidden {
  display: none;
}

details:not([open]) .open-visible {
  display: none;
}

🖼️ Use “dialog” HTML element

The “dialog” HTML element is well supported. Its goal is to simplify creating modals and popovers.

It has some rough edges, but I still find it quite useful, reducing the amount of JavaScript I write.

1️⃣ Accessible
2️⃣ Build-in backdrop
3️⃣ Auto handling of forms (example: auto-focus)
4️⃣ Stops scrolling of back page
5️⃣ Auto handle of ESC
6️⃣ Style as you wish

You still need to write code to trigger the modal and close it when the user clicks on the backdrop.

Conclusion

There is no code faster than no code.

I love writing code, but I don’t like writing “boring code” that can be handled by the ecosystem I build on top of.

Whenever I can, I prefer to use elements provided by the system.

This is the reason I follow the Open UI project. I’m particularly excited about the Stylable Select Element. 🥹

What tips and tricks do you have for writing less JavaScript? 🤔

You can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

I was very skeptical of Tailwind initially. However, when starting Angry Building, I wanted to write as little CSS and JavaScript as possible, so I decided to try Tailwind.

Over time, I changed my opinion of it. It fits quite nicely with my component-driven approach to UI.

Today, I’m going to cover tips about Tailwind CSS:

• 🧹 Use ESLint

• 🔎 Search documentation with Alfred / Dash

• 🚫 Don't use Tailwind without a component system

• 📦 How to parameterize components

  • 🎯 Targeted props

  • 🎨 Variants

  • 📏 Margins

• ✍️ Writing custom CSS

• 💡 Cool tricks

• 💨 Checkout TailwindUI

Subscribe now

So, let's get started 👉

🧹 Use ESLint plugin

When used effectively, Tailwind CSS can significantly enhance project structure. One of the initial tools I integrated with Tailwind in my projects was the ESLint plugin for Tailwind - eslint-plugin-tailwindcss.

Its biggest feature is that it validates class names because making a typo with the Tailwind class names is too easy. Before this plugin, I used a custom TypeScript checker, which worked well but was clunky.

A couple of other cool features are:

• enforces you to merge multiple classes into one

• enforces consistent class name order

• can forbid the usage of arbitrary values

• avoiding contradicting class names

For VSCode users, there is an official VSCode plugin as well.

🔎 Search documentation with Alfred / Dash

I use the Dash macOS app for offline documentation and Alfred for application launcher.

There is a plugin that integrates Alfred and Dash that works wonderfully for Tailwind.

It is especially useful when you need to discover if Tailwind supports some CSS properties and what the variants around them are.

🚫 Don't use Tailwind without a component system

To avoid messy code and improve maintainability, always pair Tailwind with a component system.

I don’t mean a design system but a component system like ViewComponent or React. Something that allows you to have reusable components.

Tailwind utility classes are applied only to a single HTML element; if you need to reuse it, you have to copy-paste the code. Then, if you decide to change it, it gets messy.

A component system is a must when using Tailwind.

I feel a lot of backlash against Tailwind because people use it as a simple CSS replacement without a component system.

📦 How to parameterize components

I found Tailwind to shine when using a proper component system. Most of your complex and log Tailwind classes are encapsulated in components in this setup. Then, you can use the flex and spacing utils to arrange those components and handle edge cases.

When we use UI components, we need to be able to configure them.

Allowing arbitrary class names to be passed around seems very easy.

This approach can lead to styling conflicts and future issues because the component must know how it’s configured. I also need help controlling which styles get overwritten. Users won’t know what is written without checking the component's implementation.

Here are a couple of techniques I use to avoid allowing class names to be passed on to components.

• Targeted props

• Variants

• Spacing

I'm going to use React as an example. I used those techniques with the ViewComponent library as well.

🎯 Targeted props

Here is an example. I have this “Text” component, and I want its font size to be adjustable. The naive approach could be the following:

<Text className="text-sm" />

However, I can’t guarantee that this will be used only for font size or restrict what sizes can be used.

Plus, how will another developer know what classes to use?

I can technically restrict TypeScript to allow only “text-sm” / “text-lg” class names. However, this will break developer expectations, and someone will overwrite when we need another configuration.

A better approach is to have a separate "targeted" property that only deals with the size.

<Text />
<Text size="sm" />
<Text size="lg" />

We can use an object map to define all allowed props. You can even apply different font weights depending on font size.

Here is the implementation:

const SIZES = {
  "sm": "text-sm"
  "base": "text-base"
  "lg": "text-lg font-semibold"
}

type IProps = {
  size?: keyof typeof SIZES
}

function Text({ size: "base" }): IProps {
   // ...
}

🎨 Variants

"Variants" is an extension of the target props pattern. Instead of targeting a single property, it allows your component to have more distinct variants.

Implementation-wise, it is the same as the targeted props—an object map with variant and class names.

I have seen two ways to this

As property

<Button variant="primary">
<Button variant="secondary">
<Button variant="small">

As component

<Button.Primary>
<Button.Secondary>
<Button.Small>

I prefer the component approach because it allows me to support different props for different variants. Some button variants support icons, and some might not.

Some components might have both variants and targeted props.

📏 Margins

The other job of having a "className" passed to the component is to set its "margin" relative to some other element on the page. However, it isn't a component's responsibility to know how it is positioned relative to another component; it is the job of the parent component to orchestrate this.

My approach to this issue is to shift from directly passing "margin" to components. Instead, I advocate for setting properties like “gap” and “padding” to their parent components or wrapping them in another component.

This ensures a more efficient and manageable way of handling margins and positioning in web development.

Here us an example:

// Bad
<div>
   <MyComponent />
   <MyComponent className="ml-2" />
</div>

// Slightly better
<div>
   <MyComponent />
   <div className="pl-2">
     <MyComponent />
   </div>
</div>

// Better
<div className="flex gap-2">
   <MyComponent />
   <MyComponent />
</div>

Max Stoiber has a good article about this subject.

✍️ Writing custom CSS

interesting CSS.Even though I use Tailwind, I still write CSS for my application.

Here are my rules for when to write CSS:

• What I want doesn’t have a Tailwind equivalent. Some fancy grid setups and things are dependent on CSS variables.

• Tailwind classes get too interconnected and hard to reason about. Usually involving styling multiple child components. When the “Cascading” part of CSS is needed.

• Automatic style. Style is applied when a data attribute is applied to an HTML element.

• I want to reuse a class name, not a whole component. An example in Angry Building is the “c-input” class name, which is applied to “input,” “select,” and “textarea,” which are wrapped by different components.

My custom css is

• In React projects, I use the CSS module in the same folder as the component.

• In Ruby on Rails projects, prefix all classes with “c-”, like “c-input” or “c-button-primary”.

• I rely on @apply, a directive to reuse Tailwind classes in my custom classes. In this way, I don’t have to remember how much is “gap-2” or “mt-3” or what is in “text-sm”

I don’t have much custom CSS.

💡 Cool tricks

Tailwind is full of cool tricks. Every time I watch someone writing Tailwind, I learn a lot. One such video is this talk by Adam Wathan (the creator of Tailwind) at Rails World 2023.

One of my favorite Taildwind features is the "group," which allows you to change the child's style based on the parent's actions. This has removed a lot of JS code.

<div class="group">
   <span class="group-hover:bg-cloud">
     When parent element (group) is hovered, I change background
   </span>
   <span>
     I don't change color
   </span>
</div>

The “grid” utilizes made the CSS grids a lot more accessible to me.

<div class="grid grid-rows-3 grid-flow-col gap-4">
  <div class="row-span-3 ...">01</div>
  <div class="col-span-2 ...">02</div>
  <div class="row-span-2 col-span-2 ...">03</div>
</div>

💨 Tailwind UI

Tailwind UI is the official Tailwind CSS components and templates project. It is created and maintained by the team behind Tailwind CSS.

These are not only great components that can be copied and pasted into a project, but they are also a great learning resource on how to write good Tailwind.

Conclusion

I have now used Tailwind in Ruby on Rails / ViewComponent and React projects, and I consider Tailwind one of my default tools.

I still write CSS; however, because of Tailwind, I now only write interesting CSS.

What I like about Tailwind is

• It makes it easy to prototype UIs

• I can copy Tailwind UI components directly and start iterating on them

• It keeps my CSS bundle small, and I have to have a single CSS file for my whole project

• It taught me to think mobile-first

• It forces consistency in terms of colors and spacing.

If you have any tips, you strongly agree or disagree with them or have ideas for something I missed, уou can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

In the next few posts, I will cover crucial tips and tricks for dealing with run-time exceptions and errors. These insights will be invaluable in your journey to becoming a top engineer.

Today, I’m going to cover tips about

• 👀 Monitoring

• 🔇 Reducing the noise

• 🔨 Fixing errors

• 📋 Processes to deal with errors

Subscribe now

So, lets get started 👉

👀 Monitoring

The tool I have used the most for error reporting is Sentry. It is one of the first tools I add to every new project I start.

I often use multiple projects for the same product. For example, at Product Hunt, we had projects for:

• [JS] Next.js frontend

• [Node] Next.js ssr server

• [Ruby] Ruby on Rails private API and admin 

• [Ruby] Ruby on Rails public API 

• [Ruby] Sidekiq background workers

Even though all [Ruby] projects used the same codebase, they had very different usage patterns and error frequencies. 

Create a dedicated Slack channel where every new error is logged. Log all deployments in this channel, as well to correlate them with any spikes in errors, making it easier to identify and address issues stemming from recent changes.

This channel is a good place to triage the errors and assign them to teammates. Each message can be used as a thread for this particular issue.

I turn off their email notifications for new errors because if it is serious, it is visible in Slack.

I keep their “Weekly Report,” which is a good overview of the week.

💡 The key here is that you or your team shouldn’t forget to check errors. Sentry should notify you.

🔇 Reducing the noise

When you start monitoring, the worst that can happen is for people to start ignoring it. This happens because there are too many errors, especially too many unactionable errors. Or, as I like to say, there is “too much noise”.

So, after you have your monitoring, the next step is to reduce the noise.

You can start reducing noise by muting errors that can’t be acted upon. Errors like routing errors or errors that containers are shutting down gracefully.

Here is an example in Ruby on Rails application:

Sentry.configure do |config|
  config.excluded_exceptions = [
    'Rack::Timeout::RequestExpiryError',        // timeout
    'Rack::Timeout::RequestTimeoutException',   // timeout
    'ActionController::RoutingError',           // 404
    'ActionDispatch::ParamsParser::ParseError', // malformed request
    'Sidekiq::Shutdown',                        // graceful process stop
  ]
end

You should be very careful here because you don’t want to start ignoring everything.

If you are too overwhelmed and know certain parts of your systems get too many errors and you can’t deal with them, temporarily create a Sentry project that acts as a “junk drawer” and redirect errors there. When you clean the main project, you can remove the redirect.

🔨 Fixing Errors

What should you fix first if you have a lot of errors? My prioritization framework is as follows:

1. 🔥 Critical errors - ones that cause major damage  

2. 😇 Most easy and noisy 

Those "critical errors" are often handled immediately because they bring the whole system down or are very complex and scheduled as part of the regular execution. 

Once the critical errors are under control, the focus shifts to the non-critical ones. The goal here is to reduce noise, so it's best to start with the easiest one (and possibly the most frequent). In this case, quantity matters more than severity.

This approach ensures that the most disruptive issues are resolved first, followed by those that contribute significantly to the overall error count

When I don't have a solution for fixing a non-critical error within 20 minutes, I move on to the next error.

💡 Fixing errors means fixing errors, not just silencing them by try-catching and ignoring them. 

Sometimes, you won't know how to fix an error, but you won't want the user to get a 500 error. In this case, you can catch the error, log it in Sentry (so you are reminded about the core issue), and return a proper error message.

You want to fix the root causes. Here is an example: the following code throws an error because “account. subscription” is null.

account.subscription.status

According to your business rules, all accounts should have subscriptions. The “bad” fix would be to check for null because this will hide the issue and make it harder to fix later.

What you should do here:

1. Check for other accounts without a subscription

2. Find out why those accounts don't have a subscription

3. Fix this

4. Add missing subscriptions to accounts

💡 Errors are valuable information about your system, don’t ignore them.

When you start fixing errors in bulk, you will start noticing patterns, leading you to build more resilient code and improve your internal tooling.

An example is when I noticed many of our background jobs were failing with random network errors, and after a couple of retries, they succeeded. So, I made our background job automatically catch network errors, reschedule, and only log the error in Sentry if the job failed more than 30 times.

📋 Processes to deal with errors

Here are some company processes I have used to deal with errors. From a management point of view, you want to have a process around errors. Otherwise, it is no-man's land.

🍸 Happy Friday

This is a process I’m currently using as a solo developer at Angry Building. Every Friday, I dedicate time specifically to fixing bugs and addressing errors, ensuring that the system remains stable and any outstanding issues are resolved before the weekend.

We used this process in the early days at Product Hunt before we reached 7-8 engineers.

A developer has dedicated time on Friday to deal with

• 🕷 Fix bugs 

• 💥 Fix exceptions

• 🔧 Bump dependancies

• 💸 Pay technical dept

⚔️ Strike Team

As Product Hunt, it became too chaotic to have this. We have had a dedicated “Strike team” consisting of 2 junior developers for some time. They were responsible for Fixing bugs and exceptions, bumping dependencies, and working with our support team. 

Of course, they didn't fix every error; if a recent feature caused errors, the team who worked on it fixed it. Or if the error was too complex, a more senior person paired with them.

🐞 Bug Duty

However, when the team crew at Product Hunt increased to 12+ people, and the "Strike Team" engineers became more senior, we disbanded the team and introduced a "Bug Duty".  

An engineer was rotated into this role in every sprint. I have written before about this process 👉 in my blog.

I think this worked a lot better than the dedicated "Strike team". 

🐛 Bug Bash

All previous tips in the post apply when you have a relatively small number of errors. However, if you are flooded, you can try to do "Bug Bash," which is exclusively focused on fixing exceptions. 

For 1 sprint, most of the team is focused only on fixing exceptions. I suggest making it fun by giving prices and titles like "toughest error", "most errors fixed", and "smartest workaround". 🏆

One couple of gotchas about this

• Good coordination is needed because multiple people might try to fix the same issue, or one can claim it and then abandon it without releasing it. You can have a Trello board with cards for each error and a limit on "In Progress" so that one developer can only have an error there.

• A lot of the fixes might be hiding root cause issues by ignoring errors.

• You need to have proper error setup and followup process otherwise in month or two you will be flooded again

Conclusion

One sign of a stable system without errors. I took a lot of care to have my system running without errors.

Handling errors is a huge topic, and because of this, I’m splitting it into a couple of posts. 

1. General tips (this post)

2. Ruby on Rails tips

3. JavaScript tips

If you have any tips, you strongly agree or disagree with them or have ideas for something I missed, уou can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

Today I’m going to cover tips about Slack. They will be split into "Personal" and "Company" sections. For bonus will list interesting channels I have seen used.

• 👤 Personal tips

  • 📢 Post in public channels instead of DMs

  • 💬 Use threads to group discussion

  • 😃 Responding with emojis

  • ⏰ Use save for later and reminders

  • 🔕 Reduce the noise from channels

  • 📇 Profile and status

• 🏢 Company tips

  • 👥 Groups

  • 🏷️ Naming channels

  • 🌐 Channels as hubs

  • 🧹 Regular channel cleanup

  • 🪝 Webhooks

  • 🌟 Interesting channels

So, here are my Slack tips 👉

👤 Personal tips

📢 Post in public channels instead of DMs

I prefer to post stuff in channels (which might be private channels). This way, many people can participate in the interactions. This is especially important when discussions are for specific projects. You will need to have a lot of channels and good channel hygiene. 

💬 Use threads for group discussion

I often hear, "I don't post in channels" because multiple simultaneous makes everything messy". The solution for this is to discuss "threads". In this way, it is easy to keep track of multiple conversations.

Slack also includes a section in its UI for tracking updates on threads that interest you. "Activity" > "💬 Threads"

Another useful tip is to summarize a thread once it concludes. Write a summary of the thread with obvious action points and conclusions. I use emojis like - ✅ and 🔜 to mark the items and post them on the main channel. So people who do not follow the discussion know about important decisions.

😃 Responding with emojis

Talking about emojis. By reading my posts, you know I used A LOT 😅

I often use emoji reactions to communicate status. I use 👀 to indicate I'm looking at something; stand by. Or ✅ When I'm done.

Here is an example of doing a Pull Request review:

Sometimes I use 👎 / 👍 as a voting system. 

Adding an emoji to a message indicates that you have seen it. Posting something is very irritating and getting zero reactions; you don't know if people saw, forgot, or just agreed.

⏰ Use save for later and reminders

You want to be responsive in Slack. However, this can be overwhelming if we get too many messages. I found the Slack "Later" and "Reminder" features useful. 

I used to try to reply to everything and move stuff into Todoist as action items. However, a "fast" response was often too "fast". So I started forcing myself to reply, "I will check this later" (I have a snippet for this) and save it for later with a reminder or not. Reminder depends on how time-sensitive something is. 

I have the time of day when I deal to save for later and use the "Slack" todo feature

🔕 Reduce the noise from channels

Slack becomes noisy very fast, and you can be overwhelmed very quickly.  

I'm surprised at how many people need to learn about the sidebar custom section feature in Slack, Which was essential for me in helping with the organization. When I was at Product Hunt, I had the following sections

• Shortcuts - most used channels for me, those changed frequently depending on the project; I was jumping around

• Engineering - this grouped every developer in my team

• Leadership - this grouped everyone on the leadership team and a couple of private channels; we collaborated

• Channels - all channels I was part of

• Muted - this was for muted channels, which I was part of but didn't care about.

It looked something like this

There will be many channels, and you often don't care about them, but you still have to be part of them. For this, I use the Slack notification setting.

A good way to figure out what channels you should mark with this is to see how often you see a channel in white color in the sidebar and how often you just click to mark it as seen and never read.

📇 Profile and status

In the onboarding tasks, I give new team members I always give them the following tasks:

1/ Set up working hours. Here is how. Because we are a global team, someone will always message you. We don't expect you to answer in the middle of the night. 

2/ Setup your Slack profile with the following data

• Profile picture - A photo of you that you feel comfortable sharing, one that will help your coworkers recognize you in a Zoom call.

• Full name - Use your real name here.

• What I do - This is shown under your picture in Slack. You can enter your official role or anything else to help coworkers understand what you do.

• Phone number - Please enter your phone number using the country code. It will not be used unless it’s an emergency.

• Time Zone - It will help Slack and anyone who wants to contact you know the time for you.

• Role - Enter your official role as per your role description.

• Team - Which team are you a part of

• Location - Where in the world do you work from? It's useful since we’re all around the globe.

3/ Set up Slack status and availability feature. Here are some of the most useful statuses. They will help you communicate why you are not instantly responsible with your team. 

• 🌴 Vacationing

• 🤒 Out sick

• 🎯 Focus

• 🗓️ In a meeting (here is how to set up)

Of course, you can use fun ones such as 🤯 Solving a hard problem.

🏢 Company tips

For the last five years, my leadership role has been to "organize" Slack and use it as a company's central hub. 

👥 Groups

Groups allow you to message multiple people at once. Initially, you can start with groups for departments like "@developers" and "@sales". Then you can have subgroups for certain teams like "@platform-team". 

If you have people on call for emergencies, you can create an "@emergancy" group that is notified when emergencies occur. You can rotate people there weekly.

🏷️ Naming channels

We know naming is hard. This is very visible when you open a Slack list of channels, which are often softer by alphabetical order. It looks like a mess 🧶

Because of this, I am trying to enforce prefixing Slack channels. Here are some of the prefixes I use:

• project-[channel] - project-specific channels, created for just a project or feature

• [team]-[channel] - channels grouped by a team like engineering, product, or support

Of course, this is hard to enforce and doesn't seem to come naturally 🤷‍♂️

I tried to use "auto-" at one point and separate bot channels from people channels for a long time. But this was a lost battle. You still want to separate channels where humans and bots interact.

🌐 Channels as hubs

One of the most efficient and underutilized features in Slack is channel bookmarks. It's a simple yet effective way to keep all the important links to the header of a Slack channel, turning it into a centralized hub for understanding a feature.

Here is an example of a project channel for a website. 

From here, we can see the project status, link to design, and metrics about the site redesign. 

The reality is that work on the project is always split between multiple tools, as many companies want everything in one place. They deal with this with links and a clear path to finding the project data.

It is also useful for other type of channels. This is an example for the "engineering-emergency" channel:

This links to the Emergency Kit document, which can guide developers in dealing with emergencies. 

Channels also support to have descriptions. Use this as well.

🧹 Regular channel cleanup

Channels are very easy to create and are rarely deleted. Because of this, I had a recurring to-do in the first month of every quarter to go through all channels and archive the unnecessary ones. 

I usually sort channels from newest to oldest because the newest channels are usually reserved for projects or special cases. Following the Lindy effect.

A couple of times, I discovered projects that were stuck. Needing a resolution. Like this one A/B test which was "forgotten" 🙈

🪝 Webhooks

Sending automated messages to Slack messages is very easy with webhooks.

At Angry Building, , we send a message to a Slack channel named 'auto-notifications' every time a new user registers or changes plans.

🌟 Interesting channels

The heart of Slack organization is channels. Here are some ideas for cool channels I have used. I prefixed with "engineering" because this was my team 😜

• "engineering-til" - "today, I learn", a place to share interesting learnings from inside and outside the company. This is one of my favorite channels. 🤩

• "engineering-prs" - a channel to request a pull request reviews. Sometimes, pull request discussions happen in threads there.

• "engineering-emergency" - when an emergency happens, this is where the team coordinates.

• "engineering-deploy" - the CI pushes a message to this channel when deployment succeeds or fails.

• "engineering-sentry" or "engineering-exceptions" - a channel in which every new exception is listed. You want this channel to be silent. It is interesting to coordinate this with "deployment" channels so you can notice when a deployment has a new influx or errors.

• “engineering-alert” - a channel to receive alerts from monitoring systems

• "engineering-daily" or "engineering-standup" - channel to a virtual standup. It might be automated with something like Geekbot.

• "product-changelog" - a channel where new features are shown to the team. I often record videos for PR. I then share those videos on this channel for a video of the features.

• "product-feedback" or/and "product-ideas" - channel(s) for sharing ideas, feedback, or bugs about the product.

• "engineering" / "product" / [team] - a catch-all channel for the team. I treat this channel as a big class in code; over time, it accumulates more responsibility, and then it is time to extract a new channel. 👨‍🎓

• "kudos" - a channel to celebrate our team members' good work and activity. 

• "fun" or "bs" or "…" - a channel to fun clips, images and etc.

If you have any tips, you strongly agree or disagree with them or have ideas for something I missed, уou can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

I have mostly worked with PostgreSQL and Ruby on Rails ActiveRecord in the last 10-15 years.

I'm splitting this post on tips into two parts:

1. General Tips

2. Ruby on Rails Tips

This part 2, Ruby on Rails Tips, today I’m going to cover tips about

• Annotate gem

• Database monitoring tooling

• Polymorphic associations

• Namespacing

• Handling race conditions and errors

• Handling JSONB columns

• Useful gems

So, here are my Ruby on Rails tips 👉

Annotate gem

The "annotate" gem is a real gem (pun intended) 🤣

It is the first gem I have installed in every new project. I would love this to be built into Rails at some point. 

It adds schema information to all Active Record models as a comment. In this way, you don't need to go to `schema.rb` / `structure.sql` or depend on your editor to get this information. 

Having this information at hand has saved me a lot of time. Especially useful part of the annotations is the list of indexes.

Here is an example:

Database monitoring tooling

The database will constantly be the application bottleneck. Good monitoring is essential because the local database has different performance characteristics and data than production.

A good and free tool is the PGHero gem. It is mounted as a gem and gives the information about:

• Duplicated indexes

• Unused indexes

• Slow queries

• Database integrity 

• Database and table sizes

• How much has the database grown week by week

• The general health of the database

For bigger projects, I reach for pganalyze. I find its Index Advisor and  Query Performance tools particularly useful.

The Query Performance helped me realize I have to move the analytics queries out of the main database to a follower replica.

Polymorphic associations

Polymorphic associations are only a very popular concept in Ruby on Rails. For the JS world, I blame their poor database tooling.

As with everything they everything, there are trade-offs. The biggest is that you can’t have foreign keys.

I find polymorphic association useful for generic and supporting domain concepts like "comments," "reactions," "notifications," and "logs," which can be attached to or connected to other things in the system.

ActiveStorage is a great example of how polymorphic associations are useful.

One issue with default polymorphic behavior in ActiveRecord has 2 drawbacks, in my opinion:

1. I can't see at one glance what are all possible records for a polymorphic association 

2. I can't restrict which records can be the parent of the polymorphic model

Example:

class Comment < ApplicationRecord
  belongs_to :record, polymorphic: true
end

What records can have comments? I don't know 🤷‍♂️

For this, I have a "belongs_to_polymorphic" helper in my ApplicationRecord:

class Comment < ApplicationRecord
  belongs_to_polymorphic :record, allowed_classes: [Post, Message, Category, Discussion::Thread]
end

Now, I can see which records can have comments. Plus, there are some other goodies to this. You can check the full implementation 👉 here.

I often add a polymorphic association to a record via concern.

module HasComments
  extend ActiveSupport::Concern

  included do
    has_many :comments, as: :record, dependent: :destroy
    has_many :visible_comments, -> { visible }, class_name: 'Comment', inverse_of: :record, as: :record
    has_many :pinned_comments, -> { visible.pinned }, class_name: 'Comment', inverse_of: :record, as: :record

    has_many :commenters, -> { distinct }, through: :visible_comments, source: :user
  end
end

I use two naming schemes for concerns  "-able" (Commentable) and "has" (HasComments).

Namespacing

I namespace my code very aggressively, including my database models.

I use a little know Ruby on Rails feature to namespace models in a module - table_name_prefix:

module Catalog
  def self.table_name_prefix
    'catalog_'
  end
end

# table name becomes "catalog_products"
class Catalog::Product < ApplicationRecord
end


# table name becomes "catalog_categories"
class Catalog::Category < ApplicationRecord
end

In some situations, it is easy to have a namespace and put all related ActiveRecord models there. For example, in AngryBuilding, I have namespaces like "Taxation", "BulletinBoard", "Calender" and "Voting". This is the easy case. 

However, sometimes, the whole namespace should be around a single record. Examples from  AngryBuilding are "Building", "Apartment" and "Issue". Those records are a domain aggregate, the root of all other records in the namespace.

I don't nest ActiveRecord classes inside other ActiveRecord classes. I created a namespace, which is the plural version of this record. 

Here is an example:

class Building < ApplicationRecord
  # NOTICE: those are not 'building_reports` or `building_manager`
  has_many :reports, class_name: 'Buildings::Report'
  has_many :managers, class_name: 'Buildings::Manager'
end

# separate namespace from root record
module Buildings
  def self.table_name_prefix
    'building_'
  end
end

class Buildings::Report < ApplicationRecord
  belongs_to :building
end

class Buildings::Manager < ApplicationRecord
  belongs_to :building
end

Handling race conditions and errors

Let's say you have an application like ProductHunt where users can vote on posts. One user can vote only once on a post. 

The way to ensure this is with a UNIQUE index in votes tables on the user_id and post_id columns. Then, in your application, you have code like:

Vote.find_or_create_by!(user: user, post: post)

Then you start noticing in your exception tracker that many requests fail with `PG::UniqueViolation`.

The reason for this is that 2 requests hit the code at the same time. Both find the return nil and try to create a vote. The first one succeeds, and the second one fails. 

The solution for this is this utility, I copy from project to project:

AngrySupport::Handle::RaceCondition.call do
  Vote.find_or_create_by!(user: user, post: post)
end

It catches the errors and reply. You can see the code in this 👉 gist.

Another group of race-condition errors I have seen is the "PG::TRDeadlockDetected" in ActiveJob workers.

I handle this with a helper in my base "ApplicationJob" class:

class ApplicationJob < ActiveJob::Base
  include AngrySupport::Handle::Job::DatabaseErrors
end

You can see the code in this 👉 gist.

Handling JSONB columns

JSONB columns are very useful. They have similar issues as polymorphic associations. You often have to guess what the structure of the JSONB column content is.

For this, the "ActiveRecord::Attributes" API comes to the rescue. It allows us to map JSONB columns to Ruby classes; this way, we don't have to deal with hashes. 

Here is an example where we use “CustomValue” class to represent a JSONB column.

First we have to define an new type

class CustomValueType < ActiveRecord::Type::Value
  def type
    :jsonb
  end

  def cast(value)
    case value
    in CustomValue then value
    in Hash then CustomValue.from_json(value)
    end
  end

  def deserialize(value)
    CustomValue.from_json(ActiveSupport::JSON.decode(value))
  end

  def serialize(value)
    value.to_json
  end
end

Then we can use this type in a record.

class MyRecord < ApplicationRecord
  attribute :custom, CustomValueType.new
end

This works not only for JSONB columns; you can use, for example, a string column to represent a custom month class - "2024-05"  😇

Useful gems

The Ruby on Rails ecosystem, which is related to databases, is rich. The Active Record itself includes a lot of batteries already 🔋

Here are some of the gems I use regularly. 

• annotate - Puts database structure as a comment in your models 

• pghero - A performance dashboard engine

• counter_culture - Enhances counter caches. I have a full post about it 👉 here.

• strong_migrations - Catch unsafe migrations in development

• database_validations - Moves validations from Ruby to database

• blazer - Business Intelligence tool as engine, allows you to write SQL and create dashboards inside your app

Conclusion

This concludes my tips for this week. 😅

ActiveRecord is one of the best and most magical parts of Rails. However, it is too easy to shoot yourself in the foot. Often, it is not even ActiveRecord's fault when we have bad database design, for example.

It would help if you had everything in front of you so you don't have to go around gathering information.  

My "belongs_to_polymorphic" helper, "ActiveRecord::Type::Value", and "annotate" gem solve for this.

If you haven't checked part 1, you can check it 👉 here.

If you have any tips, you strongly agree or disagree with them or have ideas for something I missed, уou can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

I have mostly worked with PostgreSQL and Ruby on Rails ActiveRecord in the last 10-15 years.

I'm splitting this post on tips into two parts:

1. General Tips

2. Ruby on Rails Tips

Tips, I’m going to cover today:

• Primary keys

• Keys and indexes

• Naming

• How to avoid nulls

• Dealing with Enums

• Use time as boolean

• Avoid soft delete

• Record who did it

• Split data into multiple tables

• Analytics vs application queries

So, here are the general tips 👉

Primary keys

Every table should have an "id" column for the primary key, which should be "bigint" or "UUID." I usually use "bigint."

NEVER use it as a domain value for the primary key of a table like email, IBAN, company identifier, etc.

• Data is not immutable - people can change emails.

• Can leak private data - user email shouldn’t be in the "users/:id" URL

• It can block the making of business rules and changes.  

  • I know about a company that used BULSTAT (company identifier) as the primary key of their accounts table, and this blocked them from supporting individual accounts because individuals don't have BULSTAT. 🤦‍♂️

Keys and indexes

Always have a foreign key. Except in cases where the table is for logging purposes, and data should be retained even when the related record is deleted. 🔐

In PostgreSQL, when there is a foreign key, and index isn't automatically generated. Indexes are created separately.

The big difference between an index and a foreign key is that a foreign key ensures that a column from one table matches another. For example, "posts.user_id" matches the "users. id" column. However, foreign keys don't make queries faster; indexes are used to improve performance.

Use compound indexes (index on multiple columns). If applicable, also add unique indexes. 

If there are indexes on "user_id" and "user_id, slug," for example, the "user_id" index isn't needed because the second index covers it. Order matters - "slug, user_id" doesn't use an index search on "user_id".

When having a "has_one" relationship, use the UNIQUE index.

Naming

I follow the following naming conventions.

• Date columns end with "_date"

• Times columns end with "_at" 

• Boolean columns don't start with "is_" unless I'm using Ruby on Rails; otherwise, they start with "is_" / "are_"

• Suffix columns with "_eid" for external system references, like "stripe_subscription_eid"

• Suffix tables with "_log" for write-only logging tables, like "sign_in_attempts_logs"

• Use "kind" instead of "type" because Ruby on Rails uses a type of Single Table Inheritance

• Use "record" (record_type/record_id) for polymorphic associations when I can't find a better domain name

• Use “source” as a term when one record is responsible for creating another. An example transactions table can have a source which will be what triggered the transaction

Avoid nulls

I always try to force "NOT NULL" as much as possible. 

Number columns, for example, are always "NOT NULL DEFAULT 0" by default.

Boolean columns should always be "NOT NULL" and, when possible, have a default value. 

Sometimes, you may be tempted to use null for a boolean, like when you have a new notification type and want null to indicate that the user hasn't decided on this option. There are better ways to handle this, like:

• Have an enum with "default," "on," and "off" values. This enables adding possible values like "always" or "only important ones" in the future.

• We have a separate table, "notification_preferences," with columns "name" and "enabled." The user hasn't picked a value if there is no notification record. This allows new notification types to be added without changing the database.

Often, wanting not to have null pushes me to have a better design.  🤩

Enums

I prefer strings for enum columns instead of the enum type in PostgreSQL.

This helps me avoid: 

• I don't have to run a database migration when I add new enum values. Changing code is easier than changing the database.

• I don't have to think about how to name the enum type. Naming is hard.

• I'm not tempted to share enum between tables because enum values look similar. 

(I know) I'm missing some performance gains and database constraints. When needed, I use the enum type; however, this was needed very rarely.

Rails enums, by default, are numbers - don't do this! Use the strings:

enum status: { pending: 'pending', sent: 'sent', failed: 'failed' }

Having numbers for enum can lead to "fun" situations.

Example: You have user roles: operator(1), supervisor(2), admin(3). Then you need a director role, which should be between supervisor and admin. What number will you use? 🤔

• If 4. It will be weird that 4 roles have fewer privileges than 3. Plus, the code compares roles for permission. This will mess this up. 

• If 3. Then move admin to 100 (because you want to avoid getting into this situation again). This will require costly migration and changes in the application code.

When you write an analytics query, you will waste time remembering what "4" stands for. 🫠

Time as boolean

Instead of having a boolean column, use a nullable timestamp column.

Example: Marking an apartment as archived. There are two options:

• Boolean column - "archived BOOLEAN NOT NULL DEFAULT 'FALSE'"

•  Timestamp column "archived_at TIMESTAMP WITHOUT TIME ZONE" 

I often will like to know when record was archived, so keep this as column "archived_at". 

Then, I have an index:

```

CREATE INDEX index_apartments_on_archived_at ON public.apartments USING btree (archived_at) WHERE (archived_at IS NOT NULL);

```

This technique is helpful when a state needs to be changed at a certain time. Example: "posts.published_at"

Not every boolean should be a timestamp. My question when deciding is, "Do I care when this happened?". ⏰

Avoid soft-delete

This one might be a bit controversial. 😅

Adding the "delete_at" column sounds very simple. But it rarely is. 

When we haven't soft-deleted as a concern from day one, all the queries aren't expected to be filtered by this column. 

When we soft-delete a record, we need to soft-delete everything related to it. So, one soft-deletable record makes everything around it soft-deletable.

Plus, we must upgrade the "deleted" records when we make database changes.

I often prefer a "deleted records" table where I copy data from the deleted records. I use the [auditable](https://rubygems.org/gems/auditable) for this.

The question always should be, why do we need deleted records to be around? How often are we going to restore deleted records? 

It is always about context and tradeoffs.

Sometimes, a "soft delete" is needed and can't be avoided. In this case, try to avoid its blast radius.

This is a good post about this subject 👉 Soft Deletion Probably Isn't Worth It.

Record of who did it

Often, I need a record of who performed a certain action, together with some extra information like location, browser information, and so on.

I used to attach this information to the table showing what was acted on. 

• The table becomes too big - with a lot of columns, which are often unnecessary when selecting data

• Data loss - there is only a record of the last performed action and who did it

• Explosion of foreign keys/indexes to the "users" table

A better strategy is to have a separate table for user actions, something like the following:

CREATE TABLE user_action_logs (
    id bigint NOT NULL,
    record_type string NOT NULL,
    record_id bigint NOT NULL,
    user_id bigint NOT NULL,
   action_name string,
    action_info jsonb,
    request_country string,
    request_ip string,
    request_user_agent string,
    created_at timestamp without time zone NOT NULL,
    updated_at timestamp without time zone NOT NULL
);

Split data out of tables 

When there is a big table, it attracts more and more columns. It is like a black hole. Those tables are usually the "Got object" tables in the project. ✂️

I’m always very careful when I need to add new columns to those tables.. In many cases, I prefer to have separate tables. Having separate tables is great because they are another bucket to which I can attach things. 

Often, those tables start as a "has_one" relationship to their parent table.

Perform analytics query on a follower database, not primary one

The analytics queries are very different than application queries. 

The application queries must be fast, select only a small subset of data, and avoid aggregations.

The analytics queries are the exact opposite—they use a lot of aggregations, select a larger set of data, and can be slow.

Usually, the database schema is optimized for application queries. 

It is a mistake to run those different types of queries in the same database instance. 

If you can't move your data to a separate analytics database like Amazon Redshift and Snowflake. Second best choice is to perform analytics database queries on a follower database instance. This instance can be smaller and cheaper than the primary database.

At Product Hunt, we had a follower database just for analytics. Then, we moved our daily newsletter there because newsletter generation was slowing the whole website. We later opted out of the delivery, but this was a nice temporary fix.

Conclusion

This is the end of part 1. 

When I design a new feature, I put extra care in my database design. Database changes are one of the hardest migrations you need to make occasionally.

Next week, the next part should focus on tips on Ruby on Rails and databases. I had originally tried to list them here, but they made the post too long 😅

Update: Part 2 is published

If you have any tips, you strongly agree or disagree with them or have ideas for something I missed, уou can ping me on Threads, LinkedIn, Mastodon, Twitter, or just leave a comment below 📭

To solve this problem at Angry Building, I'm using ViewComponent gem from Github.

I’m going to cover today

1. What is ViewComponent

2. When to use ViewComponent

3. Tips about using ViewComponent

4. The builder pattern

I gave a talk about ViewComponent (slides and video). This post is largely based on this post.

What is ViewComponent?

ViewComponent is a gem that allows you to create UI components encapsulated in Ruby classes. It was extracted from Github and is also used by Gitlab.

Here is an example of “FieldsetComponent".

This is how this component is going to be rendered:

<%= render FieldsetComponent.new(fieldset, title: "Bank account") do %>
  <%= form.input :bank %>
  <%= form.input :iban %>
  <%= form.input :bic %>
<% end %>

The component has two parts—a Ruby class and an ERB template

# app/components/fieldset_component.rb
class FieldsetComponent < ViewComponent::Base
  attr_reader :title

  def initialize(title:)
    @title = title
  end
end

<!-- app/components/fieldset_component.html.erb -->
<fieldset class="c-box p-4">
  <legend class="c-box px-3 py-1">
    <%= title %>
  </legend>
  <div class="space-y-6">
    <%= content %>
  </div>
</fieldset>

…and that's it. Pretty simple 🤩

The official site of ViewComponent has excellent documentation. 

Consider integrating Lookbook with ViewComponent. Its setup is just a "gem install" and adding a route.

It can't even be compared to the complexity of integrating Playbook into a Next.js project. 😜

When should I use ViewComponent?

I still use helper and partials; ViewComponent is just a new tool. Here are my rules about how to use it

I use a view component when

• I am considering extracting a partial that will be used in 2+ controllers

• considering extracting a view helper that generates HTML

• have complicated deep nested if-elsif-else (domain in view)

• copy a lot of logic around

• have to connect with JavaScript

I don't use ViewComponent when:

• a partial is only used in one controller (example: _form.html.erb)

• view helper, which is a simple pure function (example: format_money)

• there is a lot of HTML on one single page - leave it there 🤷‍♂️

Tips

Can't name a post "Tips for" if there aren't some actionable tips in the post 🧐

1. Have a “component” helper

2. Have “ApplicationComponent

3. Aliasing slots

4. Editor enhancements

Lets break those down:

1/ Have a "component" helper.

<%= render FieldsetComponent(title: 'title') %>

// becomes 

<%= component :field_set, title: 'title' %>

It is a small change, but it makes components feel more "at home" in Rails' view. Here is a gist of its implementation 👉 link

2/ Have "ApplicationComponent" base class similar to "ApplicationRecord", "ApplicationController".

Mine has only two methods, but I still find it useful.

3/ Alias "slots" to make code more readable

ViewComponent has the concept of slots. It allows you to inject content inside your component. Very useful. However, the slots methods are prefixed with "with_," which I found less readable, so I often hide the fact I'm using a slot.

class StatsComponent < ApplicationComponent
  renders_many :numbers, StatsNumberComponent

  alias number with_number
end

// I find this less readable
<%= component :stats do |c| %>
  <% c.with_number :balance %>
<% end %>

// than the alias version
<%= component :stats do |c| %>
  <% c.number :balance %>
<% end %>

4/ Have switch to alternative shortcut

I use vim-projectionist and it allows me to define shortcuts to switch between component class and template. Very handy. 😎

The builder pattern

One of the more "advanced" patterns I started doing with ViewComponent is the "builder pattern". It is similar to how Rails FormBuilder looks like. You are calling methods of the ViewComponent to define how to display the component.

Here is an example of this pattern for "FilterFormComponent"

<%= component :filter_form, params: params do |form| %>
  <% form.search :query %>
  <% form.select :user_id, options: @search.user_options %>
  <% form.select :source, options: @search.source_options %>
  <% form.date_range :date %>
  <% form.select :kind, options: @search.kind_options %>
<% end %>

In my talk, I go through even more powerful example of the builder pattern in my TableComponent, where you use the builder pattern to define rules for each cell:

<%= component :table, @search.results do |table| %>
  <% table.record :name, :itself  %>
  <% table.record :apartment %>
  <% table.number :document do |record| %>
    <% record.documents.each do |document| %>
      <%= link_to document.display_number, document_path(document) %>
    <% end %>
  <% end %>
  <% table.record :cashier, :user %>
  <% table.date :date %>
  <% table.money :cash_reserve_amount %>
  <% table.money :wallet_amount %>
  <% table.money :total_amount %>
  <% table.column :kind do |record| %>
    <%= component :transaction_kind_badge, record %>
  <% end %>
  <% table.actions do |record| %>
    <%= button_details transaction_path(record) %>
  <% end %>
<% end %>

You can check the code for this 👉 here.

Why not use Phlex?

Phlex is another way to add UI components in Rails applications. It also allows you to put your components in Ruby classes.

The main difference from ViewComponent is that it uses a Ruby DSL to define the HTML for the component. 

It is awesome, and if ViewComponent hadn't existed, I would have used it.

However, I prefer to use ViewComponent because

1. I prefer ERB over the DSL. I don't use components for everything; I only use them for reusable code. Thus, I often move code between ERB and DSL, and converting it from and to the DSL will slow me down. Or if I copied the code from ChatGPT, it will slow me down. Plus, DSL is something else I need to learn.

2. ViewComponent is backed and used by both Github and Gitlab, which gives me confidence in the project's longevity.

Those same reasons might be why someone else will choose Phlex over ViewComponent—context matters. 😅

Conclusion

For even more tips and tricks about ViewComponent, my talk is here with a video. 🙈

Choosing ViewComponent was one of the best architecture decisions I made for ViewComponent. I'll definitely use it again if I'm starting a new Rails project (where Rails renders views). 

ViewComponent should be built into Rails, too bad DHH is not a fan. 🤷‍♂️

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

Comments on your pull requests are privilege.
Receiving many comments does not imply that you have done a poor job.
It means your code is understandable enough and inspired someone to give you suggestions.

It's common for developers to feel discouraged when they receive comments on their code review. 

However, good pull requests invite comments. Most people won't bother to properly review code that they don't understand and just mark it as "looks fine".

Here are my tips for opening good pull requests:

1. Open small feature sliced pull-requests

2. Record a video walkthrough of the feature

3. Code review your code

4. Have a structured name and description

5. Have a review buddy

Let’s break these down.

1/ Open small feature sliced pull-requests

Since Github doesn't support Stacked Diffs, the PRs I open go directly to the main branch.

I'm a heavy user of Feature Toggles. They allow me to split work on the feature and deploy it before it is ready for public consumption.

I open at least 1 pull request daily when working on a feature.

Avoid opening pull requests by layer - one pull request for database migrations, then for the backend, then for the front end, and finally for tests. Often, when you get to the front end, you might notice that your database structure needs to be adjusted. 

I prefer to split pull requests into feature slices containing a part of a feature implemented end to end.

For large features, I use the "diagram as todo" technique, where I have a diagram representing the flow of the feature and color-code which parts of the feature are read and which are being worked on. 

• Green - feature slice that is done

• Yellow - feature slice in this pull request

• White - feature slice to be done

• Gray / Red - feature slice that won't be implemented

I include a screenshot of the diagram in the pull request description

You can learn more about this "diagram as todo" technique" 👉 here.

2/ Record a video walkthrough of the feature

💡 I think this is the most important tip from this post.

Before opening a pull request for review, I record a video walkthrough of this feature. There, I explain the feature and go through it. 

I currently use Loom for this purpose.

I have done it so many times that now, I need 1 take, and in 3~4 minutes, I can explain even the most complex features.

I can't count how often I start recording and notice a small bug or UI/UX issue. 🤩

I will share a link to this video in the pull request's description

When the feature is deployed, I share it in Slack with the rest of the team.

In Angry Building, we have a `#changelog` channel where I share the Loom videos with the whole company.

Afterward, our support team shares these videos with customers who would benefit from the new features.

Our marketing team will use those videos to compile our changelog email for customers.

3/ Code review your code

After I'm done with Loom, I perform a self-code review. This has also helped me to catch a lot of issues before sending my code to be reviewed by others 🕵️‍♂️

I go through the PR, pretending I didn't write it. I review it the same way I'll review someone else's pull request.

I look at every file and mark it as "Viewed" (later, if I need to make changes, this will help me to see what I have changed).

I even add comments if I need to provide extra context.

I added questions in places where I'm not sure about the approach.

4/ Have a structured name and description

I prefix related pull requests with the name of the domain or feature. So things are grouped.

Here are a couple of examples:

[Teams] Invite modal
[Teams] Invite email flow
[Topics] Assign to product
[Topics] Index page
[Funds] Transfer via transaction
[Funds] Change transaction fund
[Funds] Move between funds

For the pull request description, I used the following template in my projects:

[Ticket link](https://link-to-external-system)

[Description]

[Loom video]

## Screenshots

## Code improvements

• Ticket link to Trello, Asana, Jira, or whatever project management system is used

• Description includes

  • What is this pull request for

  • Implementation details

  • Embedded screenshot of a  diagram as todo

• Loom video from tip 2

• Screenshots, when user-facing feature

  • desktop and mobile versions

• Code improvements

  • List of system-level changes included as part of this pull-request

    • Example: “Extracted new SelectList generic React component”

  • Sometimes, those can be split into separate pull request

5/ Have review buddy

When working with small pull requests, reviewers can often lose the thread and miss the bigger picture. 

Because of this, I work closely with someone on my team to be my "buddy" reviewer for a bigger feature. I always wait for this person to merge my PRs and communicate with them about my features. 

Even if this person is not directly involved in my project, I leverage their perspective as a sounding board from day 1. Their insights and input help refine my work and ensure it's on the right track

Conclusion

Your job is to make your pull request good enough to receive comments. Good pull requests invite comments. A lot of the tips here sound like "too much work". However, with practice, those become second nature. 

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

The inherent issue is that they are out of our control.

Here are some of the common issues with external services

1. Lack of documentation - every system is different

2. Dealing with API keys

3. Unexpected errors

4. Performance issues

5. API throttling - too many calls and they kill requests

6. API pricing - usually you pay for the service, but also recently there is a new trend of paying for API access

7. How to integrate with the application

8. Lack of safe sandbox playground - often, you have to call the life system to test while developing.

9. Unexpected changes of those APIs

In my career, I have integrated with many external services. Here are some of my tips how to deal with them.

1. Keep external services code in a single place 📍

2. Wrap external services code in a facade 🎭

3. Store credentials to external services with links 🔒

4. Keep a log of calls to external services in a database 📊

5. Perform calls to external serviceс in background jobs ⚙️

Let's break these down.

1/ Keep external services code in a single place 📍

All external services live in a single place.

If I use Ruby on Rails, I have an `external` module, living in `app/lib/external/[service].rb`.

If I'm using React, they all live in `utils/external/[sercice].ts`.

This even includes code for microservices I control.

By adopting this practice, I can efficiently monitor most of the outgoing network calls from my application by simply looking at this folder.

2/ Wrap external services code in a facade 🎭

I ALWAYS wrap all external services with a facade.

Even when they have their libraries.

In this way

• I know exactly what is being used from the service

  • Updating service code or even replacing service is easier

• It is easier to test our code because I can stub the service facade.

• There is a single place, to put documentation

• Makes upgrading the service API very easy since you know where its impact points are

Ruby example

I use `extend self` facade module in Ruby, named `External::[Service]Api`. Usually, those are just bags of methods.

Here is a template for external services:

# frozen_string_literal: true

# Documentation
#
# - service: [url to service]
# - manage: [url to manage tokens]
# - api: [url to api documentation]
# - gem: [gem we are using (optional)]
# [- ... other links]

module External::[Service]Api
  extend self

  # documentation: [documentation]
  def perform_action(args)
    # use HTTParty or gem for this external service
  end
end

Here is an example for using Unsplash api:

# frozen_string_literal: true

# Documentation
#
# - service: https://unsplash.com/
# - api: https://unsplash.com/documentation
# - gem: https://github.com/unsplash/unsplash_rb
# - portal: https://unsplash.com/oauth/applications

module External::UnsplashApi
  extend self

  # documentation: https://unsplash.com/documentation#search-photos
  def search(query)
    Unsplash::Photo.search(query, 1, 12, 'landscape')
  end

  # documentation: https://unsplash.com/documentation#get-a-photo
  # documentation: https://unsplash.com/documentation#track-a-photo-download
  def track_download(id)
    photo = Unsplash::Photo.find(id)
    photo.track_download
  rescue Unsplash::NotFoundError
    nil
  end
end

Notice all the links to the documentation here.

Even when the external service has a gem to access it, the gem is never used outside this module.

If the gem returns an instance of a response object, I try to wrap it with a class I own. I expose only what I use from the services.

JavaScript example

I follow the same rules in rules in JavaScript. There, instead of a module, I export functions. I still have links to the documentation in the comments.

Here is an example of an Intercom facade:

let identified = false;

export function identifyUser(userInfo) {
  if (identified) {
    return;
  }

  if (userInfo.userId) {
    runIntercom('onShow', () => {
      window.Intercom('update', userInfo);

      identified = true;
    });
  }
}

export function openMessage(message) {
  runIntercom('showNewMessage', message);
}

export showProductTour(tourId) {
  runIntercom('startTour', tourId);
}

function runIntercom(cmd: string, args: any) {
  if (typeof window === 'undefined' || !window.Intercom) {
    return;
  }

  return window.Intercom(cmd, args);
}

External JavaScript libraries often depend on injecting scripts. I try to include those in `external` as well.

For example, exporting the Intercom script tag lives as `utils/external/intercom/script`. 
// Documentation: https://app.intercom.com/a/apps/[code]/settings/web
export default `
  (function() {
    window.intercomSettings = {
      app_id: "[code]"
    };
    (function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){setTimeout(function(){var s=d.createElement('script');s.type='text/javascript';s.defer=true;s.src='https://widget.intercom.io/widget/[code]';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);}, 4000);};if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();
  })()
`;

3/ Store credentials to external services with links🔒

The key concepts here are

1. Don't put credentials in plain text.

   1. Except when you expose API keys in frontend, those will be available in frontend anyway

2. Have credentials in a centralized placed

3. Have links where those credentials come from

4. Have comments who have added those credentials

In Ruby on Rails, I use encrypted credentials.

Credentials are stored in YAML. I always include a link to where a certain credential was taken because it is very irritating to search where a token and secret were taken, especially when dealing with Google APIs.

# Taken from: [url to where those credentials are taken]
[sevice_name]_token: [...]
[sevice_name]_secret: [...] 

I like to group all those credentials in an `extend self module` named `Config`, along with other app configurations.

Other technologies use primary ENV (Environment) variables for credentials. In this case. What I do is

1. Access ENV variables only from a single config file

   1. ...or two if I have server and client-specific ENV variables

2. Have links to where credentials were taken in this config file

I can't stress enough how important it is to have a link and explanation of where a certain API key comes from.

It is very frustrating to wonder if this is the correct key. Has it expired? Which app uses it?

4/ Keep a log of calls to external services in a database 📊

This one depends a lot on the service call. If I make external calls to something like Stripe, I only keep the `_external_id` returned by Stripe.

In Angry Building, I leverage Twilio to send SMS to users. I maintain a database table named `external_twillio_messages` to keep track of every message and its deliverability. This helps me monitor the effectiveness of my SMS campaigns and aids in cost management, as Twilio charges are based on the number of SMS messages sent.

I called Twitter API to get tweets in the past, and I only needed immutable data from them. Twitter had hard limits in terms of API rating. Having a database table `external_twitter_tweets` to store tweets helps me only to fetch data once.

5/ Perform calls to external services in background jobs ⚙️

Instead of making service calls directly in your application during web requests, you move to a background job. Those jobs should be idempotent.

When you call external services, you're making network calls. By moving these calls out of your application's main execution path and into background jobs, you are optimizing your application's performance.

In this way, if those services are down or there are network issues, your background job system will handle them.

You can combine with my previous advice and have a database table for external calls and have a flow like the following:

1. Create a record in the database with the pending status

2. Trigger background job

3. When the background job is done, mark the record as complete

4. Notify the user when completed

   1. Refresh UI

   2. Send notification

Conclusion

When you are dealing with external services, you should be very careful and isolate them from the rest of your system.

In this way, maintaining those external services is a lot easier.

Apart from that, I suggest leaving many comments with links to documentation about this external API.

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

1. N+1 queries. Where we have a list of records, and we make extra queries for each record.

2. Performing expensive count queries. Often, those queries need to do the whole table reads.

A good illustrative example is this list of posts on a site like Product Hunt.

How many queries do we need to make to implement this? 🤔

1 query for a list of posts (by some conditions)
then for every post following queries are needed
1. comments count - "SELECT COUNT(*) FROM comments WHERE post_id = $1"
2. likes count "SELECT COUNT(*) FROM likes WHERE post_id = $1"
3. list of topics - "SELECT ..."
4. has the current user liked "SELECT ...

This makes it 4 queries for every post. If we have 100 posts, this is 401 queries. 🫣 😬

In this post, I'm going to focus on two count queries - "comments count" and "likes count". How to handle "list of topics" and "has current user liked" is something I'm going to cover in the future.

Counter Cache

The way to solve these queries is simple:

Don't do those queries, store the "count" value in the "post" table.

This technique is called "counter cache".

It is quite popular in the Ruby on Rails world. It is even built in to Active Record.

The way the counter cache works is as follows

• "[parent]" table table have column named "[child]_count"

• when rows from "[child]" tables

  • are inserted, the "[parent].[child]_count" column is incremented

  • are deleted, the "[parent].[child]_count" column is decremented

The following code in Ruby on Rails will automatically handles this:

class Comment < ActiveRecord::Base
  belongs_to :post, counter_cache: true
end

Of course, we can implement this using pure SQL 👉 This is how can be done in PostgreSQL.

Surprisingly, most Node.js ORM libraries don't have this built-in, and even Elixir's Ecto doesn't have it 🤯

Drawbacks

Counter caches are great. So, I should have one for every association. 🤨

Of course not. As with every technique, it has its tradeoffs.

1) Wrong counters

As with every type of cache, keeping it up-to-date and correct is important.

2) Making write operations slow

Counter cache causes additional workload on every write, update, or delete operation, thereby slowing down these operations.

For instance, when millions of likes are created on a single post at the same time, the post-likes counter will be updated excessively, which can result in database lock issues with post rows and cause slowdowns in vote insert operations. and slows those operations.

One solution is to use the Slotted Counter Pattern.

Another solution is moving counters from the database and in something like Redis.

3) Increase storage costs

Storage is cheap, yes, but being wasteful is expensive.

Counters are often needed for the most important tables in the application. Those are also the most inner-connected tables. So, if counter cache columns are hastily added, those already big tables get many extra columns.

Every extra column adds weight when there are tables with billions of records.

4) Tooling for them outside of Active Record needs to be improved.

Outside of Ruby on Rails, I mostly work with Node.js, and the ORM database handling situation isn't pretty.

Tips for using counter caches with Active Record

This section is about Active Record because this is where I have the most experience and because it has the best tooling. 🙈

There are a couple of different ways to have a counter cache; when I add a counter cache, I start from the following list one by one and pick the first that works. 😎

1/ The built-in Active Record counter cache option for the `belongs_to` association. This is the most simple and fastest option, but it has limited flexibility.

class Post < ApplicationRecord
  belongs :category, counter_cache: true 
  
  # we explicitly the column name
  belongs :category, counter_cache: :posts_count
end

2/ The counter_culture gem with its wide range of options.

It supports switching between columns, increment/decrement with different values and etc.

class Post < ApplicationRecord
  belongs :category

  # track only the published posts count in category
  counter_culture(
     :category, 
     column_name: -> { :published_post_count if _1.published? }
   )

  # track the sum of all words in articles in the category
  counter_culture(
     :category, 
     column_name: :total_words_count, 
     delta_magnitude: -> { _1.words_count }
  )
end

3/ Custom counter cache code.

We need custom code to handle the counters when logic is so specific. For those, I use callbacks because this logic should be encapsulated.

Example: Having category -> post -> author relationship, where we aim for each category to have a "unique_authors_count", which hows the unique number of authors who have posts in this category. Implemented something like this following

class Post < ActiveRecord::Base
  belongs_to :post
  belongs_to :author

  after_save :update_category_unique_authors_count
  after_destroy :update_category_unique_authors_count

  private
  
  def update_category_unique_authors_count
    category.update_columns(
      unique_authors_count: category.posts.count('DISTINCT(user_id)'),
      updated_at: Time.current
    )
  end
end

4/ Use slotted_counters where the database table with counter cache is under heavy write load.

The idea is to split the counter column in to multiple tables. To prevent deadlocks. I used this very rarely.

More about this technique.

class Post < ActiveRecord::Base
  has_slotted_counter :votes
end

Showcase: Not only for counts

In Angry Building, I have a lot of tables with numbers like like the following.

Imagine doing an extra query for every number in this screenshot. This will be too much.

Our building tables have the following columns

• apartments_count - number of apartments

• balance_amount - counter of how much money is in the building

• monthly_fee_amount - how much fees in total pay all apartments

• obligations_amount - are how much fees are not paid

• debtors_count - how many apartments have obligations

• open_issues_count - number opened issues in the issue tracker, not total

For all those counts, I use the counter_culture gem

class Issue < ActiveRecord::Base
  belongs_to :building

  # only update "open_issues_count" when issue is opened
  counter_culture(
    :building, 
    column_name: -> { :open_issues_count if _1.opened?
   }
end

class MoneyTranfer < ActiveRecord::Base
  belongs_to :building

  # counter cache is sum of amount of the money transfer
  counter_culture(
    :building, 
    column_name: :balance_amount, 
    delta_magnitude: -> { _1.amount }
  )
end

class Apartment < ActiveRecord::Base
  # use default rails counter for "apartments_count"
  belongs_to :building, counter_cache: true

  # if apartment has obligations update counter
  counter_culture(
    :building,
    column_name: -> { :debtors_count if _1.debtor? }
  )

  # sum all monthly fees for all apartments
  counter_culture(
   :building, 
   column_name: :monthly_fee_amount, 
   delta_magnitude: -> { _1.monthly_fee_amount }
  )
end 

It is useful to have counts at the record level because it allows me to display them in the app UI without having to access the database. For example, I can decide whether or not to show a new payment button based on an apartment's unpaid fees.

Conclusion

Every time I create new tables, I think about how the records from those tables will be used, whether I need counter caches, and so on. I reach for counter cache columns very often.

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

Between January 2019 (when I started counting) and March 2023 (when I left Product Hunt to co-found Angry Building), there were only 25 recorded emergencies. This means there was less than one emergency per month. Some of those emergencies were not user-facing. 

We also had a very stable team. Our team was fully distributed between America, Europe, and Asia, so we had 24-hour coverage, and there was always an experienced engineer online. 

Because of this, in my 8 years there, we didn't have an on-call process.

However, in early 2021, after we had grown the team, we experienced a few nasty outages in a row. During these, the core team members were unavailable, leaving relatively new and unprepared team members to deal with the incidents.

Due to this, I decided to tighten our ad-hoc process. 

Nevertheless, I did not introduce an on-call role. Instead, I made dealing with incoming emergencies easier for everyone on the team. 

The process of dealing with an emergency has 3 components. I have a similar process at Angry Building;

1. Detect emergencies

2. Deal with emergencies

3. Improve the system after emergency

In this post, I'm going to walk through those components.

1) Detect emergencies

It is important to have a central place where all detection goes. I like to use Slack for this.

• “feedback”—this is where all the rest of the company posts feedback exclusively for emergencies. This is when someone notices an issue. You want this to be THE LAST place you find out about emergencies.

• “auto-engineering-sentry” - I like to use Sentry for exception tracking. This channel tracks every new exception. Usually, those are the first signs something is breaking. Both Product Hunt and Angry Building have very low numbers of unhandled exceptions.

• “auto-engineering-alerts” - a catch-up channel receiving messages from services like PagerDuty (or betterstack.com), AWS CloudWatch, etc. Monitoring tools often have a way to alert you in Slack. I always have this channel on notification.

(example of alert from "auto-engineering-alerts")

💡 Tip about Slack channel naming

I like to follow the `prefix` naming scheme with Slack channels - "[type]-[team]-[name]".
I use the `auto` type for channels that receive messages from external systems.

The key is to ensure all channels maintain low noise ratios, especially the "auto-engineering-alerts" ones. It should be an event when something is posted there.

If you haven't found out about an outage from an automated tool, one of the first action items in your Postmortems should be - "update your monitoring to detect outages" (more on Postmortems later in this post)

2) Deal with emergencies

Here, we can use two tools "the engineering-emergency" Slack channel and the ⛑️ "Emergency Kit"  documents

The Slack channel is where everyone gathers during an emergency; all communication is done there. 

The benefits of this are:

• Coordinating people  - you don't want one person reverting a deploy while another attempts to deploy a quick-fix.

• Makes writing postmortem about the incident easier because the whole history is there

• There is a history of previous emergencies that can used as inspiration

• The whole company sees that action is being taken and doesn't overload engineers' DMs.

  • For bigger incidents, the support team is in the loop so that they can communicate with our users about the incident

The Slack channel also has a link to the "Emergency Kit." 

💡 Tip about Slack channels

One of my favorite unutilized Slack features is that you can add links to channels. It is especially useful for "project-" channels where you can link to project management tools, documents, metrics, etc.

⛑️ The Emergency Kit

It is a tutorial document and links a bag of information on what to do during an emergency.

It has the following parts.

1. A video walkthrough of how to diagnose issues - should be quick (2- 3 minutes) and straight to the point. This is very useful for first-time responders.

2. Tools - links to various dashboards and tools used to manage the application.

3. Process - quickly illustrated with diagrams (see example).

4. Tips & Tricks

5. Common Issues and Solutions.

6. How-tos - after tools, this is the area I use the most.

Here a gist with my template for the Emergency Kit 👉 ⛑️ Emergency Kit

You will notice the example document uses a lot of links and <details> HTML tags. The document should be a starting point and hub that is usable for novice and experienced responders. 

I even knew all the systems by heart; I'll still use the document for the links and to copy/paste commands from how-tos.

The best way to handle issues is to start your exception tracker and then go to the database, application servers, and CDN.

If the issue isn't immediately obvious, I always follow those steps.

The usual issues I have encountered throughout my career are 

• Changes are not appearing after deploy

  • This happens if you have rolling deployments and the new version of the application can't boot. Often, exception tracking doesn't catch this, and you need to monitor one level below. If you use AWS, you can have Cloudwatch alerts for this.

• Site is very slow (more than usual)

  • The corporate here often is the database. Usually, this is a symptom of something happening - traffic spike, expensive query, etc.

  • Another option might be to use more servers/containers to handle the load.

  • Check the status pages of the cloud provider (if you use a cloud provider). Once, we had an issue due to an AWS networking outage in our region.

• There are a lot of 500s

  • Check your exception tracker; it will tell you what is failing

  • If there isn't anything there, the corporate is between services

Some evergreen tips for handling issues include:

• Revert deploys till the last working deploy

  • Beware if there were database changes

  • When services depend on each other, like frontend JS app and backend API API, revert together

• Check all recent code changes

  • focus first on the database, updated dependencies or infrastructure changes

  • look a couple days to a week back,

    • once, we had a nasty memory leak deployed a week ago

    • it was slowly creeping into our RAM

    • We saw it when we looked month data back on our RAM initialization

• When browsing, monitoring data

  • Expand to 48 hour period and look for spikes in charts

  • Watch for response time, CPU, Memory

• Isolate the issue to the lowest point in the tech stack

• Have a way to do hotfixes deploys and bypass bureaucracy like every change should have a code review

  • You should have a way even to deploy without full CI tests suit pass, to build a docker image and push.

  • This should only be used in emergencies and should be restricted otherwise. You can have a restriction in GitHub to push to the main directly, but in an emergency, the org admin should be able to allow those deploys temporarily.

Things that should be included in the "how-to" area and known by everyone is

• How to restart services

• How to revert deploy

• How to change the number of servers/containers/tasks/pods, etc

• How to quickly deploy hotfix

Throughout my career, these are the common issues I have observed.

3) Improve system after emergency

After the emergency is handled, one of the engineers is assigned to write a blameless postmortem.

Here is a gist of the postmortem template I use 👉 link.

It is very useful to keep a database of all postmortems in a tool like Notion.

Two interesting tips we do with postmortems is

1. There are explicit action points to improve the emergency kit

2. We do a system walkthrough with the whole engineering team to review the steps taken so everyone is prepared for the next emergency.

We started having a video of the walkthrough, but no one was watching it, so it was better to do it on call. 🧐

I used the postmortem to improve documentation, monitoring, and system residency.

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

Consider a feature like this:

As a shop owner,
I want the ability to add a new product category via a modal directly from the product creation form,
so that I don't have to leave the form to create a new category if one doesn't exist.

Developers often scramble to build a modal, or nowadays, they might ask ChatGPT (and go for a coffee while ChatGPT generates the code).

Most tutorials suggest something like the following:

const [isOpen, setOpen] = useState(false);

const openModal = () => {
  setOpen(true)
}

<>
  <button 
    onClick={openModal}>
    Open
  </button>
  {isOpen && (
    <Portal>
      <Modal />
    </Portal>
  )}
</>

…and this is what ChatGPT generated.

This approach, while seemingly straightforward, is naive. It works for managing a single modal but lacks basic features, such as closing the modal with the "ESC" key.

To say this approach is naive is an understatement. It kinda works if you have only one modal. It doesn't have basic features like "ESC" to close the modal.

What is worse it introduces a lot of boilerplate code, leading to a development pattern filled with copy-paste solutions. 🙄

So, let's see how to architect a better modal system.

Requirements

Before starting to build, it's crucial to consider what needs to be built.

Here are some of the obvious requirements for a good modal system:

• Provide an easy way to open and close modals programmatically.

• Allow modals to return a "result," for example, selecting a product from a search.

• Modal can be closed by

  • close button

  • ESC button

  • click/tap outside the modal

• Ensure accessibility

• Support different layout or frame types, such as a white box, full-screen gallery, etc

Less obvious requirements include:

• Modals can have URLs

  • Example: In Product Hunt, posts can be opened in modal form or as separate pages

  • We should define how the back button is handled

    • If the modal has a URL, the back should close the modal

• Modals can be stacked. A modal can open another modal.

  • Example: Modal is for product creation and can trigger modal for category creation.

• Scroll position

  • Don't scroll the background page

  • Preserve the scroll position on the page

  • Preserve scroll position on previously open modals when stacking

• Data fetching

  • Lazy loading of the JS/CSS code for modal components

  • API fetching for the content of the models

• Handle modal layout on mobile and desktop.

• There should be a way for components rendered in inside or outside modals to know this

  • Example: Infinite scroll component should listen for scroll events of a document or top modal

Architecting the Modal System

I call "support system", a code whose main purpose is to help developers build features.

The modal system is a good example of such a system. Most of the time, developers should build specific modals or open modals. They interact with the system and don't change the system often.

I tend to approach the "support systems" as functional calls. They should be "black boxes" or functions. Developers should care about their input and output, not much about their implementation.

When designing a "support system", the most important thing is to

1. Make the common operations easy (the public interface)

2. Put most of the complexity in the "black box" (the implementation details)

You should be able to change implementation details without changing the interface. In this way, you can have a partial implementation of the system and still use it to implement features.

For the modal system, the most common operations are:

• Open modals

• Implementing modal components

Let's start with those interfaces.

Open Modal

The API for opening a modal, which I have used for years has an `openModal` function, which opens a modal component.

openModal({
  content: <MyModal />
});

This function should be able to be called from anywhere. It only depends on something.

`openModal` accepts an object so that we can pass different options, like:

openModal({
  path: '/posts/id',
  frame: 'box',
  onClose: closeHandle,
  content: (
    <Post postId={id} />
  ),
});

With this simple interface, we are future proved:

• We can easily add more options in the future, like, for example, "sound", which triggers different sounds when the modal is open/closed 🔊

• We don't care if stacking is implemented. Maybe in v1, we don't add stacking for modals. 💨

• How we render the modal can also be changed later

One detail that might be missed is the `content` attribute. There, we pass a rendered React component. We can do this because JSX passed converts to a JS structure that we can pass around.

We can pass props to this component. This is how we handle the "return result" from the modal. We use a callback. 🙈

openModal({
  content: (
   <CreateCategoryModal 
     onCreate={onCreate} />
  ),
});

I have tried many more ways to pass data as a modal result, but the good old callback is still the best. 💪

Modal Component

This is where most of the implementation work will be taken. When "modal system" is mentioned, this is where people usually think - how modals look.

function MyModal() {
  return (
    <ModalUI.Frame>
      <ModalUI.Title />
      <ModalUI.Body />
      <ModalUI.Footer />
    </ModalUI.Frame>
  )
}

This is useful, and I also use this depending on the UI in the project. However, we can do even better.

Often, models need to fetch data to operate. This should be built into the model setup.

For pages, I usually extract a helper named createPage to help me with things like data fetching.

I do the same for modals - have a helper named `createModal` that deals with data fetching and modal.

Here is how it can look:

export default createModal({
  // Let's say we use GraphQL
  // Code will be similar to REST API
  query: GRAPHQL_QUERY,
  queryVariables: (props) => { ... },

  // This sets document.title
  title: (data) => data.post.title,

  // We can have other useful props
  frame: 'box',

  // Component UI
  renderComponent: ({ data, ...props }) {
    return ...
  },
});

But why not use a simple `useQuery` hook? Why all of this? 🤔

"Make the common operations easy". If we have a `useQuery`, we still need to manually write code every time to show the loading indicator, deal with errors, handle changing the document titles.

The next thing I like to do with a modal is to lazy load their code with things like  next/dynamic, so they are not included in the page bundle because modal content is often optional for the page.

Here is how that layout is out.

/components/MyModal/index.js
import dynamic from 'next/dynamic';

import dynamic from 'next/dynamic';
import Loader from '@/utils/modals/Loader';

export default dynamic(() => import('./Content'), {
    loading: () => <Loader />,
});


/components/MyModal/Content.tsx
... modal itself

For the modal, they import MyModal from @/components/MyModal, and all the rest is handled automatically.

1. Next.js lazy load the modal. We show a nice animated loader for this

2. `createModal` loads the content. It shows the same animated loader, so there is no content shift.

The `createModal` is self-contained. Some models might not use it at all. You can check a sample implementation of it in this gist. 💻

The System Implementation

We have the public interface of our system. Now, let's go into technical details.

The `openModal` and `closeModal` use the EvenBus from my previous post.

export function openModal(options) {
  emit('modalOpen', options);
}

export function closeModal() {
  emit('modalClose');
}

The event bus does the heavy lifting for this. I first extracted EventBus for a modal system.

The event bus sends those events in a `ModalContainer` component. The responsibilities of these components are:

• Listens for open/closed events

• Renders models and their overlays

• Handles stacking of modals

• Deals with scrolling

• Handles close of modals via esc, overlay

This is quite a lot and full of technical details.

The whole modal system without the UI elements is about ~ 400 lines of TypeScript.

Putting in a post will be too long (even for me). 😅

Because of this, I have extracted the code into a gist with detailed comments.

👉 Code of a working modal system 💻

Here is a video walkthrough of the code. 🍿

Q&A

Why not make this an open-source package?

I always needed more time to do so. I might do it someday.

One tricky area is that the modal system often needs various tweaks for each project.

Generalizing it as an open-source package might get too complex and heavy.

What do you think about the new HTML dialog element? How does it fit with this structure?

I like "dialog" html element. I use it a lot at Angry Building.

More people should use it.

I like this minor feature a lot -> when the dialog is opened and there are form elements, the first element auto-focuses.

What I have shown here will work with or without `dialog`

Conclusion

Now you have the wireframe of a good modal system. Of course, every application has its requirements.

One "meta" thing about the design of this system is the clear separation between the public interface and implementation details. 

We made the common operations easy and hid enough implementation details so we could easily extend the system over time.

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

Let's start with the system for “toasts”

Back in September 2020, I wrote about how I built a toast system using React.Context.

I encapsulated the logic within a ToastProvider, and the toast component itself lived in ToastProvider.Content.

import { ToastProvider } from '~/utils/toast'

// the "Provider" pyramid
<ApolloProvider>
  <ToastProvider>
    <ModalProvider>
      <Layout>
        {children}
      </Layout>
      // Reads the state and displays the toast
      <ToastProvider.Content />
      <ModalProvider.Content />
    </ModalProvider>
  </ToastProvider>
</ApolloProvider>

I had a hook to open the toast.

import { useToast } from '~/utils/toast'

export default function ShowToast() {
  const open = useToast();

  const onClick = () => open({
    title: 'This is the title for this prompt',
    content: <strong>Content</strong>,
  });

  return <button onClick={onClick}>open</button>;
}

For more details check that article.

This worked well but had a few drawbacks:

1. The “Provider” pyramid

2. When the provider value changes, the entire tree is re-rendered

3. Accessing functions to display a toast requires a hook. Therefore, it needs to be retrieved from a React component and passed around

   1. For instance, to display a toast from a Socket, React wrappers were necessary

4. I needed two components “Provider” and “Content”, so in order to understand the system you needed to read them both

I resolved these issues by using event bus pattern (publish/subscribe). With it I, eliminated the need for React.Context.

Enter evenBus

import { emit, useEventBus } from '~/utils/eventBus';

It is a simple module with 2 public methods

emit(eventName, payload) triggers an event from anywhere in my system.

useEventBus(eventName, (payload) => handle(payload)) is a React hook that listens for the event and executes a function with the event payload upon receipt. The hook also cleans up event handlers when components are unmounted.

That is it 😎

These simple primitives are utilized whenever I need to build systems for modals, toasts, notices, popovers, and similar components. In react-native I used this to handle signIn / signOut or languageChange flows.

Let's see how the Toast implementation changes when we have evenBus.

import { emit, useEventBus } from '~/utils/eventBus';

// I wrap `emit` with the functions exposed from the module
// Event bus is just an implementation detail now
// Those are more used that "Content", so they are first in the file
export function openToast(toast) {
  emit('toastClose', toast);
}

export function closeToast() {
  emit('toastClose');
}

// Only Toast Content is needed
export function ToastContent() {
  // Internal state of toast
  // For more complex systems, toast can be stacked
  // We can implemented stacking without changing the external interface
  const [toast, setToast] = useState<IToast | null>(null);
   
  // When toast is open, update state
  useEventBus('toastOpen', (toast) => {
    setToast(toast);
  });

  // When toast is closed, clear state
  useEventBus('toastClose', () => {
    setToast(null);
  });

  // Handle when there is no toast
  if (!toast) {
    return null;
  }

  return (
    <!-- render toast -->
  );
}

This ToastContent should be placed somewhere within the React tree. No restrictions.

Now, we can use openToast without a hook.

import { openToast } from '~/utils/toast'

export default function ShowToast() {
  const onClick = () => openToast({
    title: 'This is the title for this prompt',
    content: <strong>Content</strong>,
  });

  return <button onClick={onClick}>open</button>;
}

This approach resolves all the issues I encountered with the React.Context implementation.

1. No need for Providers.

2. Reduced number of re-renders.

3. Fewer hooks required.

4. Ability to open toasts from anywhere.

   1. Integrating calls from a Socket, for example, becomes straightforward.

5. Whole toast system is one simple file

Implementing modal system with evenBus

Exactly the same. 😎

A robust modal system needs to address:

• Modal stacking.

• Modals with URLs.

• Data loading for modals.

• Returning results from modals.

• Lazy loading of modal JavaScript code.

• Scrolling.

• Keyboard support.

This is big enough for its own post, ... so I wrote one 👉 “building a modal system“ 🙈

Implementation of eventBus itself

Here is the implementation of the eventBus. I've been copying and pasting from project to project since around 2021.

// Utilizing this small, dependency-free, ~100-line library
import mitt from 'mitt';

// Mapping events to their payloads
// TypeScript ensures correct event and payload usage
// Also serves as documentation for supported events
interface IEventsMap {
  // Event 'modalOpen' expects 'content' and optional 'url'
  // I name events with [module][action] format
  modalOpen: {
    content: React.ReactNode;
    url?: string;
  };

  // Passing `null` means no payload 
  modalClose: null;

  toastOpen: {
    title: string;
    content?: IToastContent;
    icon?: IToastIcon;
  }
  toastClose: null

  // Domain events can also be defined here
  commentCreated: {
     id: string;
     // ...
  };
  // ...
}

// Emitting a global event to the bus
export function emit<T extends keyof IEventsMap>(
  event: T,
  ...payload: IEventArguments<T>
) {
  if (typeof window !== 'undefined') {
    eventBus.emit(event, ...payload);
  } else {
    console.warn('emit called in server mode');
  }
}

// Hook for subscribing and unsubscribing to events
export function useEventBus<T extends keyof IEventsMap>(
  eventName: T,
  handler: (...payload: IEventArguments<T>) => void,
) {
  React.useEffect(() => {
    eventBus.on(eventName, handler);
    return () => eventBus.off(eventName, handler);
  }, [eventName, handler]);
}

// TypeScript helper type for matching an event with its payload type
// The most ✨  magical part of this file
type IEventArguments<T extends keyof IEventsMap> = 
  null extends IEventsMap[T] ? [] : [IEventsMap[T]];

// Creating one global instance of mitt
// This is an implementation detail
const eventBus = mitt() as {
  emit<T extends keyof IEventsMap>(
    e: T, ...p: IEventArguments<T>,
  ): void;
  on<T extends keyof IEventsMap>(
    e: T,
    f: (...p: IEventArguments<T>) => void,
  ): void;
  off<T extends keyof IEventsMap>(
    e: T,
    f: (...p: IEventArguments<T>) => void,
  ): void;
};

Here is a gist with the code above 👉 link.

Event Types

In each project, the IEventsMap changes to accommodate the necessary events. I've considered moving this to a separate file when the list grows. However, so far, I have had 10-15 events at most.

In my projects, I have noticed, that there are two types of events:

1. UI events - toastOpen, modalOpen, popoverOpen.

2. Domain events - userSignIn, userSignOut, languageChanged, commentCreated.

Most of my events are UI-related because they can be triggered anywhere and have a clear purpose.

I seldom use domain events in projects. For domain-related activities, there are often better patterns than an event bus.

Typically, actions related to domain objects are contained within a single screen, where passing callbacks is clearer and more straightforward.

Q&A

Should every interaction be moved to the event bus?

No, not. 🙅

The events are useful in specific scenarios and not others. It excels when you need to trigger an action from anywhere in the system without expecting a response.

Domain events, in particular, should be used rarely. There are often better patterns that can be employed.

Why not use redux / mobx / RxJS.... whatever

Many of those solutions rely on React.Context and share the same limitations as my original toast provider.

State management varies from project to project. Most often, I don't use a state library, just Apollo.

The events in eventBus often don't change state; they report that the state was changed.

Why not create an npm package?

I've considered removing mitt and creating a react-mini-event-bus npm package. However, for now, the simplicity of maintaining ~50 lines of straightforward code works for me.

Plus, I need to figure out how to make IEventsMap configurable without requiring package users to redefine function signatures. If anyone has suggestions on accomplishing this, I'm all ears. 🗣️👂

What about React Server Components (RSC)?

Lately, everyone has asked about RSC whenever React is mentioned.

I have yet to use them, as they don't address any issues I currently face. I'm not opposed to them.

Conclusion

The eventBus has significantly simplified several subsystems in my projects. However, as with every pattern, it should be used with care.

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

For me, automated testing has two goals:

1. Enables faster iteration loops

2. Ensure that when I change code, the old code behaves as it did before.

In the projects I'm involved in, I try to make writing and running a test easier than executing the code in the browser manually.

I don't care if my tests are DRY; I even see it as an antipattern in tests.

I want my test to be:

1. Reliable: they don't break randomly, don't fail when unrelated code is changed

2. Easy to understand: when I change logic, often the test needs to change as well

3. Fast: if tests are slow, people won't run them

A good test suit doesn't replace good system monitoring, error tracking and alerting.

One of the barriers to entry for writing tests is the "ergonomics" of our tools. Requiring too much ceremony or boilerplate for every test will put off even the most enthusiastic testers.

One of the reasons testing is common in Ruby Land is tools do a lot of the setup/tear down for you. Much of this comes from the tight integration of libraries like Rails, RSpec, FactoryBot, and Capybara.

In JavaScript land, things are decoupled, and you need to do too much setup/configuration. You must build your testing tools to integrate the different parts to have a sound testing story. Writing tests should be frictionless so that you can focus only on testing logic.

The second friction point in testing is speed - If it's faster to run the test, I'll do it more often. Having to wait makes you test less frequently.

The best tooling investment I ever made is integrating the vim-test and running the current test from my editor with a simple shortcut. 😇

As we talk about friction, often, people don't know what to test or how to test something. This adds friction and makes people not to write tests.

When I design systems, removing this friction is very important for me.

Here are my tips and "rules" for writing tests, which have helped me spend less time deliberating over whether to write a test and encouraged me to just do it.

Subscribe now

Today, I’m going to cover

• Terms

• The Shape of a good test

• How to deal with brittle tests

• Ruby on Rails testing tips

• End-to-End (E2E) testing tips

• JavaScript testing tips

So, lets get started 👉

Terms

Let's start with some terms I'll be using. In the realm of automated testing (as in everything in software engineering), terms are all messed up.

SUD - a system under test; this is they mode of the system while it executes tests. Often is named “test environment”.

E2E tests, known as end-to-end tests or feature specs in Ruby land. These are tests which verify a full feature from start to finish..

Example: Login, fill in a form, and verify the form is stored in the database and email is sent. These often involve running tests in actual or simulated browsers.

In the Ruby, we often use Capybara, while in the JavaScript world, tools like  Cypress are common.

Smoke tests are tests that verify code runs without an error but don't care much if the result of code execution is what is expected from the program. They just make sure nothing has blown up.

They are a good place to start when you don’t have tests or you do major rewrites.

Brittle test - test that fails "randomly". The most frustrating thing with automated tests. Tests that fail time to time. I have whole section in this post about them. 😬

The Shape of a good test

Every test you write should have four phases.

1. Setup - Put SUD in a constant state, set data needed for the test

2. Action - Perform the action we want to verify is doing what we expect it to do

3. Verify - Verify that the result of the action is what we expect it to be

4. Teardown - Puts SUD back to its initial state. This is often done automatically by testing libraries. Example: Resetting the database of all created records during the test.

Example

// test suit
describe(emojiForCountryCode.name, () => {
  // test case
  it('returns the country emoji for given country', () => {
    // no setup, because test doesn't depend on anything
    // action
    const value = emojiForCountryCode('BG');
    // verify
    expect(value).toEqual('🇧🇬');
    // no teardown was needed
  });
});

Here is a similar example in Ruby:

describe Post do 
  describe '#state' do
    it 'is scheduled when scheduled at a time in the future' do
      # setup - create post
      post = create :post, scheduled_at: 1.day.from_now
      
      # action and verify 
      # written on single line, because more readable
      expect(post.state).to eq 'scheduled'
      # teardown - cleans the database, done automatically
    end
  end
end

All my tests in every language and testing framework follow this structure.

It is fine to have multiple assertions in the `verify` step. The goal is not to have `action verify action verify`, but not a single assertion.

So, the following is fine:

describe Post do 
  describe '#schedule' do
    it 'marks post as scheduled' do
      # setup - create post
      post = create :post

      # action 
      post.schedule_to 1.day.from_now
      
      # verify the action by multiple assertions
      expect(post.state).to eq 'scheduled'
      expect(post.scheduled_at).to eq 1.day.from_now
    end
  end
end

There is one group of tests where I don't follow the four phases of testing, - the E2E tests. There, I do multiple actions and verify that the action is completed before continuing to the main step.

setup - create an unpublished blog post

action - visit post edit page
verify - the post is shown on the edit page

action - select new "published_at" date from date picker
verify - the correct date selected from the date picker

action - submit the form
verify - no errors and a success message is shown
verify - post's "published_at" is changed in the database

action - go to the index page
verify - the post is shown on the page

This is because E2E often fails "randomly," and we want to know where exactly something failed. In my example - imagine if I had a custom date picker and the JS broke for it. I didn't test the picker to set the correct value. Then, I get an error that the post has not been published. How much time am I going to lose trying to find this error?

Another thing I do with E2E tests, which is slightly controversial, is use a single test scenario for multiple related flows. This is because setup/teardown steps in E2E take too much time.

So, what I do is to test multiple things in E2E.

# I like to name my E2E tests like this
test "comment > create > edit > destroy" do
  # test create comment with empty form
  # test create a comment with fill-in form
  # test edit of comment
  # test destroy of comment
end

Dealing with brittle tests

This is one of the most frustrating experiences you can have as a developer. Some test randomly fails in CI. You have worked hard on your PR, and when you merge it into the main branch, the test randomly fails. 😡

In my experience, the main reasons for a test to fail "randomly" are:

1/ Time

Often, this is because there is some dependency on time in our test or code.

For example, we expect 30.days.ago, the month will be changed. However, if the month is 31 days or 28 days. A good practice is to freeze time with something like Timecop or isolate current time as a dependency.

Issues can arise when we compare time, too.

Example:

now = Time.now
post = create :post
expect(post.created_at).to eq now // might be 1ms difference 

2/ Leakage of state between tests

In E2E tests running a browser, those can be - cookies, local stage, etc.

I once had a randomly failing E2E test because the previous tests set something in `localStorage`, and the current test was "assuming" localStorage was empty. 🤦‍♂️

My tests in CI usually run in random order, so I had this failure when those two tests were run one after the other.

When you debug failing tests in CI with random order running, make sure locally you. Run tests in the same order, bypassing the random test order seed number.

Similar issues can arise when there are leftovers from the previous run

Fixing this is to make sure `setup` / `teardown` are strict.

E2E tests often suffer from those issues because cleaning after a test like this is often very complicated.

3/ Async code

This also affects E2E tests. In general E2E test tend to be the brittle ones 🤷‍♂️.

Example: click a button and then assert something in database changes. However, you assert that the request is still being processed.

Fix 1: Use wait_for_ajax utility like this one.
Fix 2: Fix before verifying in the database; check if page state is changed (this breaks with optimistic UI changes)

I usually do both things, just in case.

Another example: Animation is running, so the element is not visible on the page

Fix 1: Disable animation
Fix 2: Have timeouts on your DOM assertions

4/ Database order

You make a query and expect post1, post2, and post3, but you get post2, post1, and post3.

The fix is to have an explicit order set in your query or to sort before verifying if you don't care about the order.

5/ Network

If your tests make external network requests, you will see “random” failures. The solution is to block all ongoing network requests in the SUD system.

Don't forget to turn off this in E2E browser tests as well.

Ruby on Rails testing tips

I prefer RSpec over mini-test. I can write a whole post about it.

Most of my tips can be reused with other libraries as well.

What should have a test in Ruby on Rails project?

• Always test

  • The "Active" part of Rails - ActiveJob, ActiveRecord, ActiveModel

  • GraphQL mutations and resolvers classes

    • If the GraphQL type method gets complex, move to the resolver and test resolver

  • Utilities, Service, Search, Form, and Value objects.

• Don't test

  • The "Action" part of Rails - ActionController, ActionViews, ActonMailer, …

  • ViewComponents (for those previews are sufficient, imho)

  • DLS based code with something like ActiveAdmin

    • if you have complicated logic, move it out and test it

  • private methods

    • private objects who are already tested by the interface of the object using them

• Write previews

  • Action Mailer Previews

  • View Components Previews

  • You can write a smoke test that opens a browse, opens all preview pages, and makes sure nothing blows up 💥

Tips for handling context/describe/it nesting

Use .class_method for class methods and #instance_method instance method naming. It helps a lot when when reading the output.

describe User do
  # test class method User.find_and_authorize
  describe ".find_and_authorize"

  # test instance method User.new.show_cookie_banner?
  describe "#show_cookie_banner?"
end

Don't have a single `it` in multiple `context`/`describe`

describe Object do
  describe '.class_method' do
    context 'a' do 
      context 'b' do 
        it 'does something'
       end
       
       context 'c' do 
        it 'does something'
       end
    end
  end
end

# convert to

describe Object do
  describe '.class_method' do
    it 'does something when a and b'
    it 'does something when a and c'
  end
end

It is fine to have describe for each method of object

describe Object do
  describe '.class_method' do
    it 'does something'
  end

  describe '#instance_method' do
    it 'does something as well'
  end
end

Tips for using "let"

Avoid overusing “let”. The key “overusing”, it is fine to it time to time. These are my rules:

• Use let when the object global for test and doesn't need configuration like user or account. Basically objects you don’t care about much

• If any of the let objects need to be modified in “setup” phase, replace let with factory method that creates whats needed and have params.

• If you have more than 2 lets (and especially if they are calling each other), consider inlining them and using factory methods

• Don’t overwrite let between describe blocks

• Don't ever use let! it creates a lot of mystery guest issues

Here and here are good articles illustrating issues with “let”, so use with cation.

General RSpec tips

• Use the expect(value).to eq true syntax.

• Use have_attributes matcher for asserting multiple attributes per object

• Never use subject - it is very implicit and makes tests hard to follow.

• Define custom matches for common assertions, especially for supporting domain functionality.

  • Example: expect(user).to have_received_notification_about(post)

• Use shared examples if you want to verify object from a certain type behaves as an object of this type; good example are concerns behaviors

describe Post do
  it_behaves_like 'votable', factory: post
end

Tips for using Factories

I like using FactoryBot, which creates records for testing.

• Every database model should have a factory defined for

• Factories should be bare minimal (article)

• Use traits to create variants of factories (docs)

  • If you notice in a lot of tests, you do orchestration of 2-3 records to set factories → extract trait

• Include use “config.include FactoryBot::Syntax::Methods “ in your configration

  • this gives “build” and “create” factory creation methods

One big issue with factories is that they often create a lot of background records for a single record.

An example is a system with products and categories. Creating a simple product will also create a category, maybe users, an account where this user belongs... etc. You get the point.

I have found a couple of strategies to deal with this.

1. Use “build” instead “create” where possible

2. Define the minimum amount of association in default factories. Everything that the database allow nullable columns

3. Re-use records from similar relationships.

FactoryBot.define do
  factory :money_transfer do
     association :user
     association :building
     association :source, factory: :withdraw
  end
end

This will create 1 user, 1 building, 1 withdraw and 1 user and 1 building for the withdraw: Total: 5

FactoryBot.define do
  factory :money_transfer do
     association :source, factory: :withdraw
     user { source.user }
     building { source.building }
  end
end

This will create the minimum: 1 user, 1 building, 1 withdraw.

End-to-End (E2E) testing tips

I find a lot of value in those tests.

E2E tests are the best storytellers of what your system actually does.

Often, system breaks and bugs spear in the integration between layers. So having a test that tests a feature from UI to through the backend to the database and email delivery schedule is very useful.

My main goal of the E2E test is to verify

1. Layers of my system work.

2. Help me with big refactoring when I change a lot in database models and logic, but UI and flows should keep working

People don't write those tests because they are slow (to write and run) and often brittle.

Most of the problems are about tooling around writing feature tests.

Good tooling is your saver here. In almost every project I worked on in the last decade, I had a lot of tooling built around making E2E easier.

To have success with E2E tests, you need to optimize your tools for

1. speed of writing

2. easy debug when they break.

Most of my advice here will be about RSpec and Capybara. But again, a lot of my tips work with other technologies.

Tip 1: Proper configuration

RSpec.configure do |config|
  # resize the browser before every test
  # often, tests fail because UI pushes elements out of the viewport
  # if you need to test desktop / mobile sizes, you can use "it" tags  
  config.before(:each, type: :feature) do
    Capybara
      .current_session 
      .driver
      .browser.manage
      .window
      .resize_to(2_000, 2_000)
  end

  # when there is a failed test
  # 1. make and save screenshot of the page
  # 2. print page url and text
  # can't tell you how many hours of debugging those have saved me
  config.after(:each, type: :feature) do |example|
    if example.exception.present?
      timestamp = Time.zone.now.strftime('%Y_%m_%d-%H_%M_%S')
      filename = "#{timestamp}__#{example.full_description}.png"
      screenshot_path = Rails.root.join('tmp', 'screenshots', filename)

      puts "Saving screenshot: #{screenshot_path}"
      Capybara.page.save_screenshot(screenshot_path)

      if Capybara.page.current_url.present?
        puts ''
        puts 'PAGE URL: '
        puts Capybara.page.current_url
        puts 'PAGE TEXT: '
        puts Capybara.page.text
      end
    end
  end
end

Tip 2: Write the test interactively

When I need to write a complicated feature spec, I do the following:

1. Create an empty test case

2. Call the needed factory to set the database

3. Put a "debug" statement

4. Run the tests

5. Then, in the interactive console

   • I write the code step by step to verify the feature.

   • When I'm happy with the step code, I paste in the test

   • Exit when I'm happy with the result

6. Run the test with pasted code

7. Clean the test

8. Move to next task

Tip 3: Use data attributes for matching test elements

// instead of this
element.find('.description button.expand-button').simulate('click');

// write this
element.find('[data-test="test"]').simulate('click');

This clarifies what is used for testing and which is part of UI. In this way, a simple UI redesign doesn't break the test.

Tip 4: Wait for ajax

The big cause for brittle tests is to have a UI action that makes an Ajax call, where you check for Ajax call results before the call has been processed.

Because of this, in all my projects, I have a method named wait_for_ajax; it is always custom for every application.

It waits for ongoing Ajax calls to be done before continuing the test.

Here is a wait_for_ajax, I used with React application using GraphQL.

Tip 5: Write helpers for custom operations

In E2E, you often have to perform a group of related operations. It is useful to have shared helpers for those.

For example, if you have a fancy calendar picker. Every time you use it, you will have to write the following:

- click data-test="calendar-picker"
- enter the correct year in a text input
- pick a correct month from month picker
- click on the correct day
- click the "ok" button to save

Having a single helper function makes a lot more sense, so when you change "ok" with "done", you can do it in one place.

select_calendar_picker(date)

Here are some other examples for grouping operations:

login_as(user)
enter_comment_with(text)
submit_comment_with(text)
close_modal()
enter_in_from(values)

You can hide your `verify` checks in those helpers.

This is essential to have a maintainable E2E test suite. Ideally, a good test should read like a story, and its implementation details would be hidden.

One of my favorite helpers is `submit_form` (I write it customarily on every project because forms and custom form elements differ between projects):

```ruby

# regular capybara with helpers for custom inputs
fill_in 'Name', 'Rado'
fill_in_custom_calendar_picker 'Date label', date
check 'Verify'
select_from_custom_select 'Select', 'value'

# helper that hides all forms interactions
submit_form(
  name: 'Rado',
  date: date,
  verify: true,
  select: 'value'
)
```

Here is an example of an E2E test from  Angry Building. It tests the CRUD of our issue-type module. 

feature "Issue Module" do
  scenario 'types > new > list > update > destroy' do
    building = create :building

    sign_in_operator(building)

    visit account_issues_path(building.account)

    # test: create issue type
    click_on I18n.t(:page_title_issue_types)

    click_on I18n.t(:action_new_issue_type)

    submit_form

    expect_form_errors :blank

    # NOTICE this helper
    # it will raise error if there is validation error
    # name - is string
    # severity - is select
    # visible_in_app - is checkbox
    submit_form!(
      name: 'New Issue Type',
      severity: 'warning',
      visible_in_app: false,
    )

    expect_flash_message :create

    expect(page).to have_content 'New Issue Type'

    type = building.account.issue_types.first!

    expect(type).to have_attributes(
      name: 'New type',
      severity: 'warning',
      visible_in_app: false,
    )

    # test: update issue type
    click_on_edit

    submit_form(
      name: 'Updated Issue Type',
      severity: 'low',
      visible_in_app: true,
    )

    expect_flash_message :update

    expect(page).to have_content 'Updated Issue Type'

    type.reload

    expect(type).to have_attributes(
      name: 'Updated Issue Type',
      severity: 'low',
      visible_in_app: true,
    )

    # test: destroy issue type (without related issues)
    issue = create :issue, building: building, type: type

    click_on_destroy

    expect_to_be_destroyed type
    expect_not_to_be_destroyed issue
  end
end

JavaScript testing tips

Again, many of my tips (especially the E2E ones) apply for other environments.

As mentioned, testing JavaScript code is not as fun as testing Ruby. This is mostly due to tooling. Jest is good, but it can't compare with RSpec.

The code in most npm packages isn't designed with testing in mind. In JavaScript project’s, often you write a lot of glue code to connect many tiny packages.

How I test JavaScript depends on whether I use JavaScript for frontend or backend.

• If JavaScript is used for backend

  • I do a lot more automated testing with rules similar to what I do with Ruby.

  • I try to isolate and not test external dependencies.

• If JavaScript is used for frontend

  • I mostly test pure utility function

    • The heavy lift of testing is done vie E2E tests

  • In React, I sometimes just test hooks

    • I do "Extract hook refactoring" and then test the hook (video, code)

On tip: when testing with JavaScript, don't hard code names of functions:

// if you change the function name you don't need to change the test
// bonus, you know naming your function works.
describe(emojiForCountryCode.name, () => {
  // ... 
});

If you use TypeScript, do you still need tests? 🤔

TypeScript is like a smoke test, making sure your functions are called with the functions, the right arguments, and components are integrated. It helps a lot with refactoring.

It is still useful to have tests for more complicated logic and E2E tests

Conclusion

I can write a lot more on the subject of testing. However, this is getting a bit too log. 😅

People don't write automated tests due to a lack of tooling and not knowing how to write tests. I hope that these tips have helped you on both fronts.

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

Angry Building (the company I co-founded) helps manage a facility's finances and documents. This involves having the ability to export data out of the system in various formats. Our Export module handles those exports.

This module's structure is a good illustration of several useful patterns and techniques for modern web applications.

In this post, I will follow the timeline of the decision and the refactorings I did toward the current version of the Export module.

Angry Building uses Ruby on Rails, so all examples are in Ruby.

If you are not using Ruby on Rails, the techniques described in this post generally apply - see the "Outside of Ruby on Rails" section of this post

Subscribe now

The Setup

My initial set of export-related features were:

• Generate a PDF of an invoice to be shared with the tenant.

• Export CSV of generated invoices to be imported into a 3rd party. Accounting software name Plus Minus (Used by our first major client).

• Generate an Excel file of unpaid taxes of a tenant; this is used as evidence for legal cases against debtors.

• Download a zip archive of all files attached to the building.

• ...and a lot more similar like this.

As with every rapidly developed product, those weren’t grouped as an single export feature. They came as sub-tasks of other features, I was working on.

Step 1 - Service object

The first pattern I used is what we call a "Service Object" in the Ruby world. Another name for this pattern is a "Transaction Script". This is the term, I prefer because "Service Object" is often mistaken for microservice 🤷‍♂️

"Service objects" are Plain Old Ruby Objects (PORO) designed to execute one single action in your domain logic. They help with code organization and make the code easier to test. 

• I name those service objects as verbs, because they represent actions.

  • I’m fine with long and descriptive names because they are easy to search across the system.

  • Examples: GeneratePaymentInvoice or ChangePaymentAmount.

• Most of my service objects are modules with extend self and a method named call, which is the entry point of the action. 

  • When the call method gets too big, I extract the private methods to increase its readability.

• The service objects follow a procedural coding style.

  • It is fine for me the implementation of a service object to be a bit messy, as long as is covered by tests and input / output is clear.

Here is an example of the service object the "Generate an Excel file of unpaid taxes" feature:

module ExportUnpaidTaxesToExcel
  extend self

  def call(taxes)
    # ... logic
    
    excel_file
  end 

  private

  # ... helper methods
end

Because they have simple input, clear output and obvious path of execution. Service object are easy to test and read.

In some cases, a module will have many shared arguments that must be passed around its private methods. In those cases, I use a class masquerading as an extend self module.

class GenerateInvoiceDocumentPdf
  # This is what the consumers of this service are going to use.
  # Everything below this is an "private" implementation detail.
  def self.call(document)
    new(document).call
  end

  attr_reader :document, :pdf

  def intialize(document)
    @document = document
    @pdf = Prawn::Document.new(page_size: 'LETTER')
  end
  
  def call 
    watermark
    print_header
    print_company_and_customer
    print_line_items
    print_payment_info
    print_powered_by
   
    pdf
  end

  private

  # ... helper methods
end

In this example, I use a class to document and pdf attributes in every helper method without passing them around.

Sometimes, I use class to memorize some of its methods.

I use this style cautiously because it can lead to having too many instance variables and short private methods. Then, you have to do a lot of reading back and forth to follow the logic.

Here is an example:

def call
  if some_condition?
    do_something
  else
    do_some_other_thing
  end
end


def some_condition?
  some_other_condition? || some_third_condition?
end

def some_other_condition?
  @record1.some_other_condition?
end

def some_third_condition?
  @record2.some_third_condition?
end

I call this the "pretend to be an interpreter" game. To understand a code like this, you must interpret the code and keep a stack in your head. 😵

The key here is that both extend self module and class behave in the same way for the outside user of the code. 

I have had many cases where a single service object has switched styles multiple times during development, often without needing to change their tests.

Step 2 - Namespacing

One of the strategies that help me manage a large Ruby on Rails codebase is to use modules as namespaces very widely. I use namespace for every domain and group of utilities. I often move objects/namespaces around as the system evolves.

Originally, I was putting the export service objects inside of the namespace of the domain they were related to. Following the Proximity Principle and my interpretation - "code that is related should be closer together".

• PDF of the invoice, to be shared with tenant → Invoicing::GeneratePdf

• CSV export to PlusMinus → Invoicing::ExportToPlusMinus

• Excel file of unpaid taxes of a tenant → Taxation::DebtorsLegalExport

• Download a zip archive of all files attached to building → Buildings::DownloadNotesZip

This worked for a while. However, I had mistaken what is "related" in this case. An exporter is more related to other exporters compared to what it is exporting. 😵‍💫

All exporters should be grouped in the Export namespace.

In Domain Drive Design terms, the Export module is a "Supporting sub-domain".

How did I get to this conclusion?

When creating a new exporter, I almost always copy an existing exporter and adjust it to fit the new feature. I was wasting time searching for exporters to copy. 🙈

This will get even harder when I start to hire developers to work with me at Angry Building.

An even bigger issue with this structure was that spotting code for extraction and refactoring was hard because objects were spread across multiple directories and not grouped.

All PDF exporters following the same structure was not an accident of me copying/pasting. It was because the logic for generating PDFs is similar.

It is the same for Zip, Excel, CSV, etc. But I couldn't see this when the code was spread around.

I decided to create the domain namespace module named Export (very clever name, I know). I moved all service objects to the new namespace:

• Export::InvoiceToPdf

• Export::InvoicesToPlusMinusCsv

• Export::DebtorsLegalExportExcel

• Export::NotesToZip

I noticed how messy the naming was when I saw all service objects in the same directory. When I name stuff, I often try to follow predictable patterns like

[namespace][object][action] or [namespace][thing][type] or etc. This creates symmetry when you list files in a directory or have an auto-complete suggestion in your editor.

In this case I decided to go with [namespace]::[export type]::[what is exported] :

• Export::Pdf::Invoice

• Export::Csv::PlusMinus

• Export::Excel::Debtors

• Export::Zip::Notes

Having those extra modules for Pdf / Csv / Excel / Zip modules gives me the following benefits:

1. It was easy to go through all related exporters and notice opportunities for refactoring

2. I had an obvious place to put shared utilities between each exporter

Example: I noticed that all PDFs were using the  A4 paper format, so I created an Export::Pdf.a4 which returns a Prawn::Document (the library that I use for PDFs)  instance with A4 size.

Step 3 - Value object

Next, I noticed that I often copied code in my controllers that sent the files to the user:

file = Export::Csv::PlusMinus.call(invoices)

send_data(
  file, 
  type: 'text/csv', 
  disposition: 'attachment', 
  filename: 'plus_minus.csv'
)

This pushed me to exact a value object named Export::File.

class Export::File
  attr_reader :filename, :type, :content, :disposition

  class << self
    # I was considering having classes for each file type.
    # Then I decided that having couple of factory methods is cleaner.
    def csv(name, csv_content)
      new("#{name}.csv", 'text/csv', csv_content)
    end

    # ... similar method for PDF, Excel, Zip and etc
  end

  def initialize(filename:, type:, content:, disposition: :attachment)
    @filename = filename
    @type = type
    @content = content
    @disposition = disposition
  end
end

Every exporter service object now returns this value object:

module Export::Csv::PlusMinus
  extend self

  def call(documents)
    # ... logic
    
    Export::File.csv('plus_minus', content)
  end 
end

The controller code became:

file = Export::Csv::PlusMinus.call(invoices)

send_data(
  file, 
  type: file.content_type, 
  disposition: file.disposition, 
  filename: file.filename
)

This push me to extract a simple controller helper method:

file = Export::Csv::PlusMinus.call(invoices)
download_export(file)

# ... in ApplicationController
def download_export(export_file)
  send_data(
    file, 
    type: file.content_type, 
    disposition: file.disposition, 
    filename: file.filename
  )
end

The value object can also be integrated with Active Storage:

file = Export::Pdf::Invoice.call(document)
document.file.attach(file)

Integration

Rails has this format feature, which allows a controller action to respond differently depending on the requested file format.  

I use this to the full extent. Here is what my invoices controller looks like:

class InvoicingDocumentsController < ApplicationController
  def index
    # Find an account that current user has access to.
    # I'll write about this authorized strategy in a future post.
    account = find_record Account, params[:account_id], authorize: :view

    # Search for documents based on search params
    # I'll write about SearchObject in a future post.
    @search = Invocing::DocumentsSearch.new(account, params)

    # URL: /account/[account_id]/invocing_documents.[format]
    # Depending on the URL's file format return HTML/ZIP/XLS/PDF/CSV.
    respond_to do |format|
      format.html
      format.zip do
        download_export(Export::Zip::Invoices.call(@search.all))
      end
      format.xls do
        download_export(Export::Excel::Invoices.call(@search.all))
      end
      format.pdf do
        download_export(Export::Pdf::InvoicesCombined.call(@search.all))
      end
      format.csv do
        download_export(Export::Csv::PlusMinus.call(@search.all))
      end
    end
  end
end

In the UI, I have a filter form for invoices, and when the user has filtered down to the invoices they want to export.

The ViewComponent for the menu, just".format" to the URL and return what was selected.

<%= render ActionМenuComponent.new(title: :download) do |menu| %>
  <% menu.action :button_zip, url(@search.account, format: :zip, **@search.params) %>
  <% menu.action :button_plus_minus, account_invoicing_documents_path(@search.account, format: :csv, **@search.params) %>
  <% menu.action :button_excel, account_invoicing_documents_path(@search.account, format: :xls, **@search.params) %>
  <% menu.action :button_pdf, account_invoicing_documents_path(@search.account, format: :pdf, **@search.params) %>
<% end %>

Future expansion

Work is never done.

A couple of features in the Angry Building roadmap will involve moving the file exporters to be performed in a background job because exporting more data on demand in a web request is not a good idea. I have a couple of ideas on how to morph the structure to handle this case. I'll sure write a follow-up post when this happens.

I use libraries directly in the service object to generate PDF and Excel files. I might create wrappers around those and use the builder pattern to make the exporters themselves simpler. Will see when I get there.

Outside of Ruby on Rails

At first sight, what I have described so far looks very Ruby on Rails-specific. 🤨

However, I have also used all the techniques from above in Node.js projects. 🧐

Let's imagine I have used Node.js and TypeScript for AngryBuilding. What will the export system look like? 🤔

• I will structure the directories as I did with the namespaces.

• All exporters will be functions instead of service objects;

• The file value object will be TypeScript type, created via factory methods.

Here is what the directory will look like:

lib/export/index.ts
lib/export/file.ts - factories for value object
lib/export/pdf/utils.ts - all utils for PDF will be
lib/export/pdf/invoice.ts - an exporter
lib/export/excel/utils.ts - all utils for excel will be
lib/export/excel/invoices.ts - an exporter

Here is how the utilities going to look like:

// lib/export/pdf/utils

// Forward those so exporters have fewer imports
export { filePdf, IFile } from '../file'; 

export function a4() {
   // ...
}

// ...

The exporter will look like something like this:

// lib/export/pdf/invoices
import { a4, filePdf, IFile } from './utils';

// IFile is optional since TypeScript can infer
export default function(document): IFile { 
 
   const content = a4();

   // ...

   return filePdf(`document-${document}`, content);
}

The exporter can used as this:

import generateInvoice from '@/lib/export/pdf/invoice'

As you can see the structure looks very similar.

Most of the differences will be in the glue of the system - libraries used to generate the various formats and the code sending them to the user.

Conclusion 

The Export modules is a good illustration, how I think about software design and system evolution .

In this post, I have outlined some the essential patterns for a modern Ruby on Rails application:

• Service objects

• Namespaces

• Value objects

The patterns, shared can be used not only in Ruby on Rails projects.

Subscribe now

p.s. I’m experimenting with companion videos for my posts. 

I hope you find them useful.🤞

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭

Welcome to my Substack newsletter - Rado's Tips.

Since this is #1 post of the newsletter, if you are reading this:

a) you are a friend who I nagged to subscribe
b) you will be a friend because you subscribed on your own
c) you don’t know me and randomly arrived here.

In all cases, thank you 🙏

A bit about me:

I'm the CTO and Co-Founder at Angry Building 🔥, SaaS for facility management and neighbour communication platform (with the goal to rebrand as HappyBuilding 🙈).

Previously, I was Head of Engineering at Product Hunt 😺.

I have been working in tech since 2002. My first tech job started as a joke when I was 15, it is funny story 😅.

This newsletter is an experiment, and I still don't know what the format will be. I will figure it out as I go.

I'd be happy if you joined me on this journey.

I plan to write at least once a week. I want to keep this practical and focus on sharing showcases from my experience.

Some of the posts will have a video explainer, which I'll post on YouTube.

I have been inspired by other newsletters like Refactoring and The Pragmatic Engineer.

My writing style includes extensively

• numbered and bullet-point lists

• emojis, gifs 😅

• code samples

• diagrams

• step by step think process walkthroughs

Why I'm starting this Substack? 🤔

1. I'm often asked for advice and have a handy note ready to share. A central place to keep and link to my tips will be handy.

2. This will force the function to group my notes and thoughts into more coherent ideas.

Why am I not just using my existing blog? 🤔

1. With a newsletter, you push content to interested people; with a blog, you need to pull people to your content.

2. I'm using Substack instead to implementing newsletter capabilities to my existing blog because

   1. I want to deal with only some of the machinery of a newsletter system I manage. I have implemented the Product Hunt Newsletter delivery system and know how much work this involves. [spoiler] I plan todo a detailed post about the design of that system in the future 🤫

   2. Substack has a building reach tool that hopefully will help me grow this newsletter, motivating me to write more.

If you have any feedback for me you can leave a comment or ping me on Threads, LinkedIn, Mastodon or Twitter. 📭

Before, I had a good back catalog - here are things I have written before and you might like:

• Collaborative Single Player Mode - remote, process and management

• Remote Onboarding - remote, process and management

• Product Hunt Architecture - showcase and software architecture

• Manager Journal - management and productivity

• Tips for End-to-End Testing - testing, javascript and ruby

• Refactoring First vs Change First - software engineering

• My Advice to Junior Developers - software engineering

• Testing GraphQL Backend in Product Hunt - graphql, ruby and testing

• Dealing with N+1 in GraphQL (part 1 and part 2) - graphql and ruby

• Graphql Optimization Story - story, graphql and react

• How I use React.Context - react

• Extract React Hook Refactoring - react

• Organizing External Services in Rails - ruby on rails

• How Not Implement Html Editor - story and software engineering

• Bug Duty Process - process