DEV Community: Factorial

Don't create leftovers (DCL)

Ferran Basora — Thu, 26 Nov 2020 19:09:57 +0000

Everybody is familiar with the DRY principle in software engineering coined by Andy Hunt and Dave Thomas. It states do not repeat yourself in code to achieve less ambiguous code, avoid redundancy, and many other benefits in the long term.

In this post, I want to explain another pattern that I see over and over in all kind of projects and it brings problems and impacts the maintainability of your software project. It doesn't affect the source code itself but the organization of the files that compose it.

What is a leftover?

In the lifespan of a software project, code gets created and destroyed to meet users' expectations. During this period, it is easy to generate files, components, and other kinds of stuff that are not used any more. Those undesired pieces of software, make it harder to maintain, impact on your internal metrics, slow down your Continuous Integration check and other kinds of side effects.

Those leftovers from the past, don't bring any value to the project and it can get to the point where nobody is brave enough to do a right cleanup to have a healthy codebase. This goes directly to the technical debt bucket.

Those items should have been removed when the last reference to them disappeared but a developer forgot to remove them. Those leftovers can be a unused image, a unused copy, a unused test on your test suite, etc.

You can find many similarities and parallelisms with the responsibilities of a memory garbage collector. It keeps tracks the dependencies between parts, with a reference counting to be able to destroy all unused references. The problem here is that we don't track this kind of information between the dependencies in our code base.

Why do we create leftovers?

This bad design pattern can have many shapes. This is another example where Don't create leftovers impacts many projects today. How many of you have a translation system where translations live in one place and the place where they are used is in another one?

src/translations/en.json

{
  "hello_world": "Hello World!"
}

src/components/hello_world.jsx

export default function HelloWorld () {
  return (
    <div>{i18n.t('hello_world')}</div>
  )
}

The problem with this translation approach is that if the HelloWorld component disappears in the future, the copy in en.json will be forgotten unless a developer remembers to clean it up. At some point in the future, your main translation file starts to have hundreds of unused keys that make you lose money with each new language you want to support.

Some translation systems are aware of this and follow a much better approach. They have an extraction
step to retrieve all translations from the codebase. With this, the list of used copies (dependencies) is always up to date.

Other examples

How many times have you seen a web platform tutorial where the assets folder and the place where they are used is far away?

Take this easy file structure:

/assets/images/
  - post1-cover.jpg
  - post1-thumbnail.jpg
/posts/post1/
  - helper.js
  - index.jsx
/specs/
  - helper.spec.js

This structure can be familiar to you, but it suffers from DCL. If for some reason the post1 is no longer needed and it disappears, it is really probable that the helper.spec.js file will be removed after a failing test but those assets related to post1 will be forgotten forever.

Check this other example:

components/
  List/
    index.jsx (has a dependency with ListItem)
  ListItem/
    index.jsx
stories/
  List.story.jsx

Although this file organization seems inoffensive, it suffers from DCL too. If the List component disappears, maybe the List.story.jsx will fail as a side-effect but nobody will alert you that ListItem needs to be removed too.

How to detect it?

This principle shows up like references to parent components or external resources, but sometimes it is harder to detect it.

The rule of thumbs in all cases is to answer yourself the question:

If I remove this component or piece of code from my code base, will I create leftovers?

With this question, you imagine yourself in the future removing this shiny new code and seeing all the unused pieces in your source code. Answering this question at this point helps you to know all the dependencies this code has.

Better approach

To fix this organization problem, the best approach is to encapsulate better all the dependencies. In the case of file structures try to avoid having dependencies to parent components if a dependency is only used once and move them as child components. All those dependencies can start to use relative paths.

Following the previous example, this would be a much better organization:

/components/
  List/
    ListItem/
      index.jsx
    index.jsx
    index.story.jsx

This new approach has much better encapsulation and a clear set of dependencies. One direct benefit of this is that it lets you move this component to others around without breaking it.

In some cases, like the translations example, you will need some extra step in your toolchain to resolve those dependencies of your views. In the case of the assets one, you will need your builder (Ex. Webpack) to have support to resolve them.

Conclusion

We just reviewed a few examples of the don't create leftovers principle.
Understanding the consequences in terms of maintainability, you will be able to create and organize your components in a better way that will let you maintain your code base in a healthier way in the long term.

You don't need to take this principle as written in stone. There are always exceptions or edge cases, as in DRY principle, we don't have to fall on the wrong abstraction as Sandi Metz mentioned. You have to use it and keep it
in mind when you structure your components, views, assets or
whatever piece in your project.

I hope this post helps you to spot this pattern sooner rather than later to keep the maintainability of your project under control.

Happy hacking!

A trick with the Ruby documentation

Fran C. — Tue, 28 Jul 2020 06:28:47 +0000

I've never been able to remember the arguments for Array#reduce. Every time I think I've managed to do it I just get it wrong.

Luckily for me, Ruby has very good documentation on its standard library and, what's even better, it ships with a CLI to explore it so I don't even need to Google it 😬

ri "Array#reduce"

= Array#reduce

(from ruby core)
=== Implementation from Enumerable
------------------------------------------------------------------------
  enum.reduce(initial, sym) -> obj
  enum.reduce(sym)          -> obj
  enum.reduce(initial) { |memo, obj| block }  -> obj
  enum.reduce          { |memo, obj| block }  -> obj

------------------------------------------------------------------------

Combines all elements of enum by applying a binary operation,
specified by a block or a symbol that names a method or operator.

The inject and reduce methods are aliases. There
is no performance benefit to either.

If you specify a block, then for each element in enum the block
is passed an accumulator value (memo) and the element. If you
specify a symbol instead, then each element in the collection will be
passed to the named method of memo. In either case, the result
becomes the new value for memo. At the end of the iteration, the
final value of memo is the return value for the method.

If you do not explicitly specify an initial value for
memo, then the first element of collection is used as the
initial value of memo.

  # Sum some numbers
  (5..10).reduce(:+)                             #=> 45
  # Same using a block and inject
  (5..10).inject { |sum, n| sum + n }            #=> 45
  # Multiply some numbers
  (5..10).reduce(1, :*)                          #=> 151200
  # Same using a block
  (5..10).inject(1) { |product, n| product * n } #=> 151200
  # find the longest word
  longest = %w{ cat sheep bear }.inject do |memo, word|
     memo.length > word.length ? memo : word
  end
  longest                                        #=> "sheep"

It has a very good interactive mode as well (ri -i) In which you can search whatever you want :)

Oh, and if you use Vim you can access it by using K over any word. Check this out:

Why most developers fail their first tech interviews

Gerard — Mon, 11 May 2020 07:32:50 +0000

In the last 4 years interviewing candidates for development roles, I've come to realize the cohort with the highest rejection rate is applicants to entry-level positions.

What pains me to see is that most of them fall off the recruitment funnel for the simplest of mistakes, which often have nothing to do with their professional skills and could easily be avoided. These aren't failures of skill, but of communication.

In this post, we will go over the developer recruitment process at
Factorial, mostly as an excuse for me to explain what is it that makes so many entry-level candidates flop their interviews, and how you can avoid it.

The process

The recruitment process is simple: two interviews, one more generic let's-meet type of interview, and another more technical. After the second meeting, you
either get rejected or get a job offer.

The first meeting is mostly innocuous: an opportunity for us and the candidate
to assess whether we are a good match. The only piece of advice I can give you
at this point is to be honest, not be a jerk and ask as many questions as you
can. Ideally, you want to leave this encounter convinced whether you want this
job or not. We will answer almost any question you might have, and you should be
wary of any company that isn't willing to do the same.

Once introductions have been made, you will be asked to submit a take-home
exercise that will require you to write a representative chunk of your own
code. If you are prolific enough, we will gladly accept another program you
might have already developed. The second interview basically consists of you
going through your own code with some devs from our tech team. You'll get asked
technical questions about your submission and some more general aspects, if the
conversation takes us down that path.

The purpose of this exercise is many-fold, from evaluating general technical
abilities to assessing reasoning capabilities but, mostly, the purpose of this
exercise is to evaluate how well would you do the job we want you to do. Most
of these aspects are correlated, but if you fail at the latter you won't get
hired.

This is, unsurprisingly, where most candidates flop. Let's see why.

All candidates look alike

Truth is, for entry-level positions, there's little variance in the candidates'
technical skills.

We get candidates with brilliant exercises that cannot defend it accordingly
during the interview, candidates with lesser code that fair rather well during
questioning, candidates obsessed with CS theory, others more of the
learn-as-you-go type, variant degrees of experience, creativity,
resourcefulness... In the end, all these aspects average out, painting the
portrait of the default entry-level applicant who is capable of writing a fairly
decent program involving frontend and backend code, sometimes with some extra
sprinkles of infrastructure code on top.

Put another way, statistics say that if you made it to the tech interview portion
of the recruitment process you probably have the technical skillset required to get
hired. This won't always be the case but, generally, the rule holds true.

Now, if all candidates look alike, what is it that distinguishes them apart? What
makes recruiters pick one over the many others?

I'm convinced it's communication. More specifically, knowledge communication.

The success of a tech candidate is a function of their knowledge and how well
they can communicate said knowledge.

Given that we have established most junior candidates have similar technical
knowledge and that, unsurprisingly, most developers suck at communicating, you
can see how this ends up with a high rejection rate of entry-level applicants.

Let's explore further this notion of knowledge communication, and see how you can
exploit it to improve your odds at your next tech interview.

Know your code

Mind you, when I speak about communication I'm not implying you can talk your
way through the recruitment process and end up at a cushy dev job with no
technical skills to show for. At the tech interview, the beans will get spilled
and your knowledge boundaries will be put to bare. Knowledge communication
requires, well, knowledge; You have to do the work and learn your computer
sciency stuff first.

Problem is, often developers spread their knowledge surface large and thin,
sometimes too thin. They learn from repetition, which leads to a lack of
understanding, which results in poor knowledge communication.

Let's say you, as a candidate, learn about the new fancy framework du jour,
follow its documentation examples and, with today's tools, you quickly get a
pretty decent app up and running. You already look like 99.9% of the other
candidates. You even got professional stuff out of the box: JSON Web Token
authentication, cross-site scripting protection, WebSocket support, and whatnot.
You start feeling confident and end up submitting an exercise that contains code
that looks like this:

class ApplicationController < ActionController::Base
  protect_from_forgery unless: -> { request.format.json? }
end

This is the candidate's code. If I git blame it, their name will show up. And,
yet, most entry-level candidates have but a vague idea what this code does.
The result is candidates communicating their lack of knowledge about their own
code. They cannot answer what their software does and, what's worse, why it
does it.

You have to know your code.

To tackle this issue, I recommend candidates take a much more deliberate
approach and think in terms of knowledge communication. If you are an applicant,
run over every line of your exercise before you submit it and ask yourself: "Can
I explain this line of code?". This will immediately beg questions about the
what, why, and how of every piece of your program you didn't really grasp,
deepening your knowledge.

What's more important, this approach will set you down a path of reinforced
learning: Discovering how XSS protection works will take you through HTTP
headers, the different types of HTTP verbs and codes, maybe you'll understand
how your framework uses JWTs to manage your users' sessions and what this pesky
CORS error is all about.

At this point, you will arrive at the tech interview with knowledge not only on
how to build a program with a particular framework, but on how the underlying
infrastructure of the internet works to support the many features your framework
provides and your app makes use of. You will be able to communicate your
knowledge about your code and even respond to some extra curveballs the
interviewer might throw at you. Your skills will be immediately more
transferable, as all frameworks rely on the same underlying infrastructure.
You'll be a better engineer.

Sadly, you won't be able to answer everything, since the purpose of the tech
interview is precisely to test the limits of your knowledge, so let's see what
you can do about that.

Addendum: Other examples of poorly understood code I often encounter are JWTs,
OAuth, Polymorphism, db indexes & foreign keys, HTTP basics, React component
lifecycle methods, JS Promises, async/await & generators. You don't need to know
all of these but, if it's in your code, you should.

Know your unknowns

If you follow the aforementioned prescription, you'll quickly reach the second layer of your circle of competence: things you know you don't understand very well.

For example, you might feel brave and make use of the new useEffect hook from React:

const CatCounter = ({ cat }) => {
  const [counter, setCounter] = useState(0)

  useEffect(() => {
    setCounter(counter + 1)
  }, [])

  return `I have counted ${counter} cats so far!`
}

Now, useEffect is hard — otherwise, its creator wouldn't have written a
gazillion-line blog post about it — and you probably don't understand very well why you have to put that empty array as a second argument. You know, though, that if you don't the counter does not seem to refresh with every new cat you pass it as an argument. You have a thin knowledge of this piece of your code, and this is a problem.

As a rule, do not try to hide your knowledge gaps in code. You'll open
yourself to getting a question you will be playing guessing games against.
Instead, simply admit it:

const CatCounter = ({ cat }) => {
  const [counter, setCounter] = useState(0)

  // NOTE: I am not sure why I need this second argument but otherwise the
  // component does not seem to update on prop updates. Need to investigate.
  useEffect(() => {
    setCounter(counter + 1)
  }, [])

  return `I have counted ${counter} cats so far!`
}

Communicating a lack of knowledge is also knowledge communication.

You are admitting your knowledge gap, implying you know this is a problem but had to move on with it, and announcing your intention to fix it. It shows self-awareness, curiosity and the drive to improve; the kind of potential we look for in candidates at this level. It’s not a simple “I don’t know”, which would be lazy, it’s a reasonable utilitarian argument that tacitly admits failure of understanding.

At this point, the interviewer can do little more than ask if you had time to follow on your investigation which, given the circumstances, is an excellent outcome.

Addendum #2: Of course, if your exercise contains many comments like these you should reconsider whether you are ready to apply for the job. Nevertheless, do not be afraid to admit gray areas in your understanding.

Wrapping up

Most entry-level candidates are very similar, and it’s highly unlikely you’ll be the exception. Instead, focus on deep knowledge vs thin understanding, specially about those concepts you know you might get questioned about. If you can, don’t answer only with “I don’t know” but don’t play guessing games either, state your knowledge gaps, what you think you know about them, and how you plan to improve on these gray areas.

There are many more aspects we could explore in preparation for your first tech interviews, but these are the foundational aspects all candidates should be aware of. The rest, we'll explain in upcoming entries.

Cheers, and good luck in your next interview.

This post originally appeared at https://gerardclos.com

A set of programming aphorisms at Factorial

Gerard — Wed, 15 Apr 2020 09:33:54 +0000

At Factorial, we maintain an engineering Handbook where we document aspects such as common abstractions, programming principles and documentation of our architecture.

Among these, there are a set of aphorisms stemming from coding best practices and common pitfalls we have been encountering during the last 4 years building our product. Let's share some of these.

Beware, these aphorisms are language-agnostic and, thus, you might find them more or less regularly in your day to day depending on the characteristics of your preferred programming language.

Depend on contracts rather than data structures

This is my personal favorite because it's so simple yet so ubiquitous. Put
bluntly, data structures make for lousy interfaces: they are often opaque, mutable and nullable, all characteristics you wouldn't want for an interface — and yet we use them as such constantly.

The most common example is accepting a hash as a method argument:

def method(hash)
  puts hash[:foo][:bar] # This can print something, null or raise an unexpected error.
end

NOTE: This is especially prevalent in languages that make it easier to work with data structures and nullables such as Ruby or Javascript.

Using a data structure introduces an implicit dependency between your method and the data structure's shape, a dependency that could have been easily avoided by simply passing the expected value:

def method(bar: nil)
  puts bar # This can print something or null
end

In cases where the dependency with the data structure cannot be avoided, isolate it behind an API:

def method(hash)
  puts HashAccessor.new(hash).get(:bar) # This can print something or null
end

class HashAccessor
  def initialize(hash)
    @hash = hash
  end

  def get(attr)
    # ...
  end
end

Although this might come across as a superfluous refactor it minimizes the spread of the dependency and paves the way for a future refactor in which we would get rid of this data structure dependency altogether.

Avoid null values

Hardly a surprise. All the new cool kids in the block are using it.

The problem with null values was already hinted at in the previous aphorism: it's a very hard contract to enforce. This will result in errors happening far away from the underlying issue:

# main.rb
ROLES = { admin: 'admin', manager: 'manager' }
role = ROLES[user.role]
user_presenter(role)

# user_presenter.rb
def user_presenter(role)
  return 'Admin' if role == ROLES[:admin]

  ManagerRolePresenter.render(role)
end

# manager_role_presenter.rb
def manager_role_presenter(role)
  "#{role.capitalize} – Lead" # << Unexpected `capitalize` message for `nil`! This is very far from the origin of the `nil` and hard to fix
end

To avoid null values you can enforce types (if your language supports it), implement the optional pattern, use a custom contract with data validation (such as a Struct) or directly raise an exception closer to the null source.

Code should be greppable

Or, put another way, do not be too smart for your own good.

As a rule of thumb, your teammates should be able to easily navigate your code using only a pattern-matching tool like grep (or ctrl-f for those using fancier editors).

If that weren't the case it probably means your code is not explicit enough and is hiding dependencies with dangerous techniques like meta-programming:

module Jon
  class Snow
    # ...
  end
end

# main.rb
  def main
    "Jon::#{name}".constantize.new # This can blow up
  end

As if the potential error wasn't bad enough, this technique obfuscates the
author's intention and makes navigating your code more difficult than necessary.

To avoid these pitfalls and improve code quality make extensive use of static analysis tools
such as linters or static type analysis.

In the particular case of meta-programming, replace it with a good ol' Map or switch statement.

Depend on abstractions rather concretions

Lastly, a general principle. If you take a look at most of our previous examples and their proposed solutions, they all share a common property: the solution implements an abstraction.

Do not depend on data structures, depend on an abstraction that gives you access to the underlying data. Do not depend on nullable values, depend on an abstraction that handles the nullable state for you... You can see the pattern.

The advantage of abstractions over concretions is that they change less often, and this is good for code maintainability:

You often cannot control the amount of changes over time, but you can control the number of dependencies. Stay away from zone B and you will be fine.

That's it! We hope you will find some useful tips from this list that you can put to good use in your daily coding practice.

Cheers.

Some reasons to avoid Hashes in Ruby and some alternatives to them.

Fran C. — Mon, 16 Mar 2020 08:23:28 +0000

So, hashes, uh?

What's good about them?

They are easy to build
They are cheap (short-term cheap at least)
They help interfacing with shapeless data (like JSON) in an easy way.
They are good to build simple/cheap key-value stores in memory.

What's not so good about them?

They are shapeless (in a bad way, you never know what you expect from them)
They are mutable (in a bad way as well, how do you know nobody else will mutate this or nobody has already mutated it?)
They are dummy (unlike objects, they know nothing, they have no way to interface with except for Enumerable)
They are impossible to type (🤷‍♂️)
They need a lot of defensive code with nil checks. (even when they are getting better at this with things like hash.dig(:key1, :key2) it is not enough and you always need extra checks here and there, which makes the code difficult to read and to change).

So, what should we do with them?

I propose that we all agree on a small set of guidelines to help us answer the question "Should I use a Hash for this?". TL;DR

Avoid using Hashes as input to methods. Try to have shaped inputs.
Avoid using Hashes as return values. Try to have shaped return values.
If you receive a Hash, isolate it. Build a layer to interface with instead of the Hash.
- Get the data directly if it is a small hash.
- Build objects if it has an heterogeneous structure.

1. Avoid using hashes as input to methods.

There's no easy way to know what's inside params here..

MyInteractor.new(
  author: author,
  params: params
).call

Instead use this:

MyInteractor.new(
  author: author,
  value: params[:value],
  question_id: params[:question_id]
).call

You now have an explicit knowledge of the input for that interactor which is:

simpler to use (you don't need a Hash now, only values which can come from any object)
Intention revealing
Typable
Easier to document

Try to avoid substituting the Hash with a T::Struct or a plain Struct if you don't use sorbet. You will be adding an extra layer and having very little in return. You avoid the hash, which is good, but you add an extra layer and win very little in return. That does not justify a new layer.

Instead, type the parameters you're receiving individually with Sorbet. If you don't use sorbet, just avoid the struct and pass them individually.

You might think:

But I have A TON of parameters and a Hash is a nice and convenient way to
make my object easier to use!

It isn't. You're sacrificing a lot in exchange for almost nothing and your code will suffer for it.

Another reason to avoid this is that it can imply security holes. There's a very simple example which is mass assignment model attributes from the controller params.

# NOTE: This is not how our code works, this is an example of how NOT to do it
current_user = current_company
  .users
  .find(session[:current_user])

current_access.update!(params[:user])

Can you spot the issue? It is subtle but it is there. An attacker could just send a company_id and inject themselves on any company 😱. Not good.

This kind of issue is what made Rails end up adding the strong parameters API: https://guides.rubyonrails.org/action_controller_overview.html#strong-parameters but that isn't enough. Strong parameters are focused on avoiding mass assignment. But you massively pass params from a controller into any object as parameters you're exposed to this kind of problem as well.

In short: Be as explicit as possible with contracts. Pass unfurled parameters as a preference and type as much as you can.

2. Avoid using hashes as return values.

If whoever uses the code you write doesn't know what to expect from your return value, they'll have a hard time using you. Make it easy for them.

If you need a dummy object, use a T::Struct instead (or a Struct). They are very good for transferring data, they have a defined shape and they are highly typable.

3. If you receive a Hash, isolate it.

Let's give an example, you get a Hash from reading a YAML file, a JSON response from an API or even on a controller action.

This is, by far, the hardest to solve among all the cases because each one will need a different solution.

There are however some guidelines you can follow which help a bit:

1. Isolating hashes: Get their values

If you only need to get some keys from the Hash, e.g. reading the params on a controller. You're good to go. Slice the keys you need and then read them.

class MyController
  def create
    MyCreateInteractor.new(
      author: current_access,
      value: create_params[:value],
      description: create_params[:description]
    ).call.unwrap!
  end

  def create_params
    params.slice(:value, :description)
  end
end

Soon we will be able to use sorbet for this, which will give use shaped and typed params. Until that moment arrives, we need to deal with it.

2. Isolating hashes: Build a defensive layer

If the Hash has layers with more hashes inside of it and you need to extract data from it through Enumerable methods (find, map, select...) then wrap that hash on an object and interface with that object instead.

There's an example of this on our PdfParser library. Its configuration is a YAML file with a shape like this:

---
some_data_table:
  min_x: 55
  min_y: 111
  max_x: 532
  max_y: 167
  transform:
    type: table
    arguments:
      - name: column1
        transform: text
        max_x: 214
      - name: column2
        transform: text
        max_x: 372
      - name: column3
        transform: money_es
        max_x: 532

some_numeric_field:
  min_x: 217
  min_y: 81
  max_x: 265
  max_y: 99
  transform: money_es

Interfacing with a hash like this is problematic because you don't know what to expect. Have a look at the transform for example. On the numeric field, it only has a name. But on the table; it has a type, a list of arguments and more nested transforms.

Let's first understand the problem:

This file represents the format for a PDF file. A format has many different fields inside (some_numeric_field and some_data_table for example) in this case.
Each field has boundaries to where it is found on the PDF
Each field defines a transformation to be applied to it after reading the text on it. E.g.: money_es means that it is money formatted like 1.000,00 and it has to be transformed into a BigDecimal

How did we get over this? Interfacing with a Hash like this could have been really complex so we started by separating the parts that change from the parts that stay the same.

All fields have boundaries
All fields have a name
All fields have a transform

What is the changing part? The transform can be different per field so we defined something like this:

Field = Struct.new(:name, :boundaries, :transform)
Box = Struct.new(:min_x, :min_y, :max_x, :max_y)
Transform = Struct.new(:type, :arguments) do
  # @param args [Hash]
  # @option args [String, Hash] :transform the name of the transform or a
  #   Hash describing it
  # @option :transform [String] :type the name of the transform
  # @option :transform [Hash] :arguments a hash with the arguments for the
  #   transform
  def self.from_hash(args)
    type, arguments =
      case args[:transform]
      when String
        [args[:transform], nil]
      else
        [
          args[:transform][:type],
          args[:transform][:arguments]
        ]
      end

    new(type, arguments)
  end

With that we build objects from reading the file into a Hash like this:


# name is the key of the YAML definition for a field and arguments is a hash
# with its content.
read_file.map do |name, arguments|
  Field.new(
    name,
    Transform.from_hash(arguments),
    Boundaries.new(
      arguments[:min_x].to_i,
      arguments[:min_y].to_i,
      arguments[:max_x].to_i,
      arguments[:max_y].to_i
    )
  )
end

We only read from the hash in 1 place (when parsing the configuration).
We have a specific initializer for the case in which we need to pass a hash around (Transform.from_hash) and we use a case...when to map it into objects.

It is indeed more work but saves you from a lot of pain later on. Nobody will know this all came from a Hash, nobody will try to read a shapeless object and nobody will try to mutate it.

What are Hashes good for?

They are good as in-memory key-value stores. But even in that case, build a layer to isolate yourself from it. As an example:

We use this object to store an in-memory cache of the hierarchical relations between employees and their managers. Fetching them is costly and because of our permissions architecture, we do it a lot.

class HierarchyCache
  def initialize
    @cache = {}
  end

  # If a key has value, return it
  # if it doesn't store the return value of `block` and return the value
  def fetch(key, employee, &block)
    value = get(key, employee)

    return value unless value.nil?

    set(key, employee, block.call)
  end

  # Get the value stored on a key
  def get(key, employee)
    @cache.dig(employee.id, key)
  end

  # Sore a value for a key
  def set(key, employee, value)
    new_cache_entry = { key => value }

    if @cache[employee.id]
      @cache[employee.id].merge!(new_cache_entry)
    else
      @cache[employee.id] = new_cache_entry
    end

    get(key, employee)
  end
end

We use a hash here but we take care of not letting anybody know we do and most importantly, we don't leak how the hash is structured and we provide a programmatic API to interface it.

Summary (AKA TL;DR)

Avoid using Hashes as input to methods. Try to have shaped inputs.
Avoid using Hashes as return values. Try to have shaped return values.
If you receive a Hash, isolate it. Build a layer to interface with instead of the Hash.
- Get the data directly if it is a small hash.
- Build objects if it has a heterogeneous structure.
Use them as long as nobody can call [] or any other Enumerable method on them.

Last, but not least, don't serialize things into hashes if you intend to use them later on. If you find yourself using [] on different layers of your code check if you can enforce any of the previous points.

Summarized even more

Don't use them to build contracts (as inputs/outputs). No problem as intermediate values (as long as you isolate them well enough).

A handful of engineering principles at Factorial

Pau Ramon Revilla — Tue, 18 Feb 2020 11:08:01 +0000

I will be honest. The first prototype of Factorial was built with Phoenix (Elixir). Nothing is more exciting to a crafter than to try a new tool. This one will be different, better perhaps. But it was not the time for tinkering: our goal was to launch Factorial's first version under one month. We threw the prototype to /dev/null and turned to the tool we knew best, Ruby on Rails.

Spoiler: We launched our minimum viable product and successfully built a company around it.

The most important priority for a technical founder is the speed of learning. You have a limited amount of time – let's be honest, cash in the bank – and you need to find product/market fit. But the biggest challenge is to learn fast while establishing a solid foundation, layering engineering principles to build upon. Nothing too specific nor rigid. Just a handful of concepts paired with some early abstractions that illustrate them. After all, the first lines of code you write will surely disappear, but the founding principles may prevail. Tweaked, twirled and twisted, but still there.

So, what were those principles in Factorial?

First Principle: Verbs as first-class citizens

Most programs are modeled after human language constructs. Objects are nouns and methods verbs.

Hence, if we say:

Hellen rejects John's last time off request

We tend to imagine the program like such:

class User
  has_many :time_off_requests

  def last_time_off_request
    time_of_requests.last
  end

  def rejects(time_off_request)
    time_off_request.update(rejected: false)
  end
end

hellen = User.find_by(email: 'hellen@example.com')
john = User.find_by(email: 'john@example.com')

hellen.rejects john.last_time_off_request # Reads like english, yai!

With time you start to realize that this is the wrong way to go about it.
As much as we feel nice and cozy when a program reads like English, it is not a good architectural principle. It's easy to confuse familiarity with good design.

Rails abuses the English language metaphor. I've always been amazed that one of the pillars of the framework is the omnipresent Inflector, a class that is responsible for the singular/plural forms which all the Rails conventions are based upon. And don't get me wrong, the English metaphor is probably one of the reasons Rails succeeded. It felt magical yet familiar to beginners, but in my experience, it falls apart in complex domains.

In Rails nouns are glorified and belong to the realms of ActiveRecord. Please all stand-up and show respect to the king of all subjects, the almighty User model. After all, most sentences in your applications are in the form of user <verb> <predicate>.

But verbs? They are an afterthought. To represent verbs we use methods in models and controllers. Both implementations are hard to reuse, one for being coupled to the database and the other with HTTP framework abstractions. And then you have strong parameters in the middle coupling both to make things worse.

At Factorial we decided early on that we wanted verbs to be first-class citizens. When we explored a new domain we've asked ourselves which verbs would be part of it. We've resisted the temptation to model everything under CRUD/REST conventions and instead embrace domain-specific verbs. One does not say: "Hellen updates John's last time off request with rejected = false" but instead "Hellen rejects John's last time off request".

We've implemented this by introducing a new type of object called the Interactor. This is not a new concept at all, but we've embraced it to the point that our applications do not look like a Rails application anymore: Our ActiveRecord models are very small, they don't use any callbacks and most of the business logic is implemented on the Interactors instead. We've also removed the need for strong parameters since controllers never talk to ActiveRecord directly. The verbs in our application are reusable, and more importantly, composable.

Second Principle: Share memory, split domains

We started Factorial at the peak of the microservices hype. "Microservices" encompassed a lot of different concepts, from scaling to organization topologies. Most of the ideas revolved around a very well known problem:

As applications grow in size complexity increases exponentially making it harder to operate (for both machines and humans).

The microservices approach is to impose a paternalistic constraint on how to build software. It mostly bans shared memory so developers can't "cheat" the boundaries on their systems. Some people even go as far as to ban shared databases to keep domains completely isolated. By creating strict boundaries you ensure developers behave accordingly. We love constraint-based architectures but we wanted to explore another set of trade-offs. Can we have non-paternalistic boundaries?

We've modeled our application as a monolith (sacrilege!) but separating each domain in a different engine. Those are our boundaries, soft but effective. No hardware constraints, no ban o shared memory and most importantly, no ban on shared databases. Our domain is highly relational so it is critical for us to be able to commit transactions across domains and sacrificing joins is not an option yet.

It's the developer's job to ensure that boundaries are respected. I would be lying if I told you that we do. Sometimes we violate them knowingly (strictly speaking, incurring technical debt), others unknowingly. And yet, I believe the trade-off is a sweet spot for Factorial.

Our rule of thumb is: "If we decide to remove this feature, how easy would it be to delete its code?". Optimizing for code removal early on has compounding benefits in the long run. And trust me, we've removed a lot of features until finding product/market fit.

Third Principle: Everything must be audited

Some of the tools and techniques from the present are shaped by constraints from the past. This is very obvious when you work with relational databases. They were built with a space constraint that does not hold true anymore: Storage prices have decreased from $30,000/GB in 1989 to $0.019/GB in 2018 source.

This constraint is the reason why most relational databases are mutable. They don't hold all the historical information. They update or delete rows when they are instructed to do so. A notable exception is the binlog which is mostly used for replication purposes (although is becoming more common to connect it to a data sink to be able to gain back that information).

We decided early on to store a record for each verb that was invoked. Yes, storage is cheap and we wanted to be as verbose as we could. We wanted to know what users have done with the system so we could solve their issues and eventually ask temporal questions: What was the salary of that given employee two months ago? Can you get all the contract changes in the last month?

This turned out to be one of the most difficult but rewarding principles to implement. We've discovered that we could also use those audit events as a mechanism for domains to communicate with each other. Auditing events became the glue between the first and second principles. A verb triggers an event that can be listened to by another domain. Beautiful!

But this was actually not our invention. Without knowing it, we've stumbled upon Domain-Driven Design. Most of these concepts have been explored during the last decade: Verbs are shaped after the ubiquitous language, domains are bounded contexts and audit events are common among event sourcing and event storming practitioners.

Conclusion

The take here is that principles are important but must be vague enough. People joining your organization will come with new ideas. If they find rigid and strict principles they won't be able to influence the team. At Factorial we hire engineers from different backgrounds and it had a very positive effect on our engineering practices: Each developer has brought their own experiences from other languages and ecosystems and built new tools on top of those vague and flexible foundational principles. It's so enriching.

A trick with Ruby anonymous classes

Fran C. — Fri, 14 Feb 2020 14:47:12 +0000

Since everything in Ruby is an object it is only normal that classes are objects too. Which means they just have regular constructors with initializers, as any other object would do.

Class.new do
  def hello
    puts "Hello world!"
  end
end.new.hello

# prints -> Hello world!

What can I use it for?

Anonymous classes are an amazing candidate for testing mixings.

# callable_test.rb
# run it with:
# ruby callable_test.rb

module Callable
  def call(*args)
    new(*args).call
  end
end

require "minitest/autorun"

class TestCallable < Minitest::Test
  def setup
    @klass = Class.new do
      extend Callable

      def initialize(arg1, arg2)
        @arg1 = arg1
        @arg2 = arg2
      end

      def call
        [@arg1, @arg2]
      end
    end
  end

  def test_same_return
    assert_equal @klass.new(1, 2).call, @klass.call(1, 2)
  end
end

# Run options: --seed 3295
#
# # Running:
#
# .
#
# Finished in 0.000605s, 1651.9615 runs/s, 1651.9615 assertions/s.
# 1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

There's a caveat though... You need to be aware that anonymous classes have no name (they are anonymous after all ;) ) so any call to Class.new.name will return nil.

Classes only acquire a name when you assign them to a constant. That is:

klazz = Class.new
klazz.name
# => nil

MyClass = klazz
klazz.name
# => "MyClass"

So, if you need to test things which depend on the class name you can't use anonymous classes, although they still have a benefit over regular declarations on tests, which is that they can be assigned to variables, while regular class...end declarations can't.

my_class = class MyClass; end
my_class
# => nil

other_class = OtherClass = Class.new
other_class
# => OtherClass

So, if you need a class with a name on a test you can still use this, only remember to remove the constant on your test's teardown.

Object.send(:remove_const, :MyClass)

If you're on a Rails app and use RSpec, it even has a helper to test things with anonymous controllers: https://relishapp.com/rspec/rspec-rails/v/3-9/docs/controller-specs/anonymous-controller, which is especially useful to test things like login/logout flows independently.

A trick with Ruby Hash.new

Fran C. — Wed, 12 Feb 2020 06:54:29 +0000

Hashes are used a lot in Ruby (sometimes even abused) and they have a very interesting functionality that is rarely used: Hash.new has 3 different forms

Regular form

It just returns an empty hash whose unexisting keys return always nil.

h = Hash.new # Or h = {}
h[:hello] # => nil

This is just equivalent to using an empty Hash literal also known as {}.

Fixed default

It allows for a parameter which is returned in case the key doesn't exist.

h = Hash.new('world')
h[:hello] # => 'world'

This form needs to be used carefully though since you always return the same object, which means if you modify it, you modify it for all subsequent calls:

h[:hello].upcase! # "WORLD"
h[:foo] # "WORLD"

That is why only recommend using this option in a case: maps of classes.

POLICIES = Hash.new(ForbidAllPolicy).merge({
  admin: AccessAllPolicy,
  user: RestrictedPolicy
})

policy = POLICIES[current_user.role]

POLICIES[:user]
# => RestrictedPolicy

POLICIES[:hacker]
# => ForbidAllPolicy

Why classes but not other objects? Because classes are singletons (a singleton is an object that only has one instance at the same time) so you do not care that you're always going to get the very same object all the time.

Calculated default

This form gives the biggest freedom since it allows us to pass a block to calculate the value and even to store it on the hash. So the next call to that same key will already have a value.

h = Hash.new do |hash, key|
  value = key.upcase
  puts "'#{key}' => '#{value}'"

  hash[key] = value
end
h["hello"]
# prints -> 'hello' => 'HELLO'
# => "HELLO

# Next call to the same key is already assigned, the block isn't executed

h["hello"]
# => "HELLO"

My preferred use case for this is to protect myself from nils and to avoid continuous nil checks.

In a case like this:

h = {}
h[:hello] << :world
# => NoMethodError (undefined method `<<' for nil:NilClass)

You can either ensure the key is initialized

h = {}
h[:hello] ||= []
h[:hello] << :world
h
# => {:hello=>[:world]}

Or use the trick we just learned to ensure you will never have a nil and you get a sane default instead.

h = Hash.new { |h, k| h[k] = [] }
h[:hello] << :world
h
# => {:hello=>[:world]}

Take into account that passing around a Hash like this might be dangerous as well. Nobody will expect that a Hash returns something for a key that doesn't exist, it can be confusing and hard to debug.

If we get keys for the previous hash:

h.keys
# => [:hello]

How to use it then? Just do not let the rest of the world know it is a Hash 😬

class CachedUser
  def initialize
    @cache = Hash.new { |h, id| h[id] = User.find(k) }
  end

  def fetch(id)
    @cache[id]
  end
end

cache = CachedUser.new

cache.fetch(1)
# => select * from users where id=1
# => <User: @id=1>

cache.fetch(1)
# => <User: @id=1>

Although the example is extremely simple it showcases how you can safely use a Hash as a container object safely without exposing some of its drawbacks but profiting from its flexibility.

A trick with Ruby array literals

Fran C. — Mon, 10 Feb 2020 09:49:24 +0000

Declaring an array in Ruby is simple:

ary = ["foo", "bar"]
# => ["foo", "bar"]

but did you know you can save the array elements as variables the same time you declare them?

ary = [
  foo = "foo",
  bar = "bar"
]

foo # => "foo"
bar # => "bar"

Looks like magic? Well, it is not magic. This happens because assigning a value to a variable is an expression in Ruby. This is applicable to many other cases, like assigning a value on a conditional

if user = User.find(params[:id])
  puts "User is #{user.name}"
end

Or even crazier: to save the parameter you pass to a method!

def some_method(arg)
  puts arg
end

some_method(value = "Hola")
# prints -> "Hola"

value
# => "Hola"

Disclaimer: ☝️ those 2 might be bad ideas. I wouldn't use it regularly on any code I write but knowing it is possible is always a good thing.

What can I use this for?

It plays quite well with constants that can then be used as some kind of enums:

COLORS = [
  COLOR_RED = "RED",
  COLOR_BLUE = "BLUE",
  COLOR_GREEN = "GREEN",
  COLOR_YELLOW = "YELLOW"
]
# => ["RED", "BLUE", "GREEN", "YELLOW"]

On rails apps they are especially useful to declare scopes:

scope :non_red, -> { where(color: COLORS - [COLOR_RED]) }
scope :blue, -> { where(color: COLOR_BLUE) }