simplicity-principles

Simplicity Principles

Write code that is simple, necessary, and unsurprising.

Three Core Principles

1. KISS - Keep It Simple, Stupid

Simple solutions are better than clever ones

What Simple Means

• Readable by developers of varying skill levels
• Fewer moving parts and abstractions
• Direct and obvious implementation
• Easy to debug and test
• Minimal cognitive load

Elixir Examples

# COMPLEX - Over-engineered
defmodule PaymentCalculator do
  use GenServer

  def start_link(_), do: GenServer.start_link(__MODULE__, %{}, name: __MODULE__)
  def calculate(items), do: GenServer.call(__MODULE__, {:calculate, items})

  def handle_call({:calculate, items}, _from, state) do
    result = Enum.reduce(items, Money.new(:USD, 0), &Money.add(&2, &1.price))
    {:reply, result, state}
  end
end

# SIMPLE - Just a function
defmodule PaymentCalculator do
  def calculate(items) do
    Enum.reduce(items, Money.new(:USD, 0), &Money.add(&2, &1.price))
  end
end
# Use GenServer only when you need state/concurrency

# COMPLEX - Unnecessary abstraction
defmodule UserQuery do
  defmacro by_status(status) do
    quote do
      from u in User, where: u.status == ^unquote(status)
    end
  end
end

# SIMPLE - Direct query
def active_users do
  from u in User, where: u.status == "active"
end

def inactive_users do
  from u in User, where: u.status == "inactive"
end
# Macros only when you need metaprogramming

TypeScript Examples

// COMPLEX - Over-abstraction
class UserDataManager {
  private dataSource: DataSource;
  private cache: Cache;
  private transformer: DataTransformer;

  async getUser(id: string): Promise<User> {
    const cached = await this.cache.get(id);
    if (cached) return this.transformer.transform(cached);

    const raw = await this.dataSource.fetch(id);
    await this.cache.set(id, raw);
    return this.transformer.transform(raw);
  }
}

// SIMPLE - Direct approach
async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}
// Add cache/transform only when performance demands it