Ahmed Omran

Compose Software Like Nature Would - RubyConf 2024

Wed, 20 Nov 2024 00:00:00 +0000

Many years ago I gave a talk that combined biology and software design to a local JavaScript meetup. It was an interesting concept so I proposed it as a talk for RubyConf 2024. Surprisingly it was accepted! The slides can be seen here. The video can be seen here.

Talk Summary

The only constant in software development is change. When our software cannot adapt, it turns into a big ball of mud. It becomes hard to reason about and hard to change. On the other hand, living organisms have the incredible ability to adapt to their environment. Over eons, they evolved innumerable adaptations. Let’s explore together how we can create adaptable, maintainable, and resilient software with some inspiration from nature.

The conclusions of the talk are:

Build small components (modules, classes)
Compose them together with messages (methods, events)
Have strong boundaries (limit public interfaces)
Use names, domain language and folder structure
Push side effects to the edges
Iterate and evolve your design over time

Resources

Gary Bernhardt - Boundaries
Dan North - Software that Fits in Your Head
Rich Hickey - Simple Made Easy
Jessica Kerr - Functional Principles for OO Development

People first

Mon, 30 Oct 2023 00:00:00 +0000

I have not written anything on this website in many years. I have had the pleasure and great privilege of being completely lost in my work on impactful projects over the past six years. The work has been challenging, and the people have been great. I write this as a reminder to myself that what makes a great team and organization is people.

Manage with empathy and put your people first. As an individual contributor, make yourself indispensable to your team. Teams can do extraordinary things when they are empowered and supported.

Manage with people first in mind

People want “deep work” – meaningful problems and meaningful decisions.
People want to be treated with respect – flexible schedules and a lot of autonomy.
People want their accomplishments acknowledged – fair compensation and a clear career path.
People want to grow – managers and mentors invested in their future.
People want time for themselves and their families – sensible hours and long-term planning.

Leaders have a big responsibility to focus on the needs of others before their own. The trust that you build with a people-first approach will buy you a lot of goodwill, and you can then, in turn, get more from your team.

Making yourself indispensable to your team

As an individual contributor (non-manager role), there are skills that software engineers need, no matter the context. These skills can make you indispensable to your team and help you grow into a leadership role.

Presence

Presence isn’t just clocking in. It means being there for others and benefiting from your colleagues being there for you. An indispensable team member:

can be easily reached during regular business hours for their time zone unless the time is blocked off on their calendar.
shows up to all meetings on time and ready to engage.
responds to all code review requests within 24 business hours.
- asks questions when they don’t understand the code changes.
- offers advice, suggestions and encouragement in code reviews.
- When someone reviews their code, engages with the reviewer and addresses their concerns.
when they get stuck on a problem, they ask questions and get support from their colleagues.
actively uses the company’s communication channels (e.g. Slack) to help their colleagues, give their opinions, ask questions, and answer questions.
monitors production environment logs and alerts for bugs and performance issues.

Ownership

Great teams are full of leaders – people who know what they’re working on and why they’re working on it and can get projects to the finish line. They

understand the real-world problem they are trying to solve. If they don’t know why they are doing something, they actively engage with their manager, and colleagues to understand better.
break down the project they are working on into smaller milestones and communicate their progress.
communicate risks and help reduce the scope of a project if the timeline is unrealistic.
remove roadblocks, get unstuck, help people make decisions, and push projects to the finish line.
think about the state of their codebase and actively work to improve it.

Software Design

The first step is to find a solution; often, the first solution is suboptimal. Iteratively, the solution is then refined. A talented and experienced engineer knows when to stop. They know that:

not all code is created equal. I often ask myself: How do I make my code easier to read? How do I make it easier to change in the future?
conversely, there is no perfect code. They have the wisdom to ship the working code and improve it later if necessary.
They write automated tests and ask others to do the same.
They evaluate trade-offs (refactor or not? their code or a third-party solution?) and understand why they made a decision.
They evaluate the software design of the entire codebase and help their colleagues make good decisions.

Delivering solutions

Beautiful code is only worthwhile if it ships or solves a real problem.

Sometimes, the solution involves writing no code.
Sometimes, the solution does not need to solve all use cases (80/20 rule).
Solutions should be broken down into small changes that are easy to understand, easy to review and less risky to merge.

Rails View Components

Sun, 15 Oct 2017 00:00:00 +0000

Ruby on Rails is a framework that delivers a tremendous amount of developer productivity and happiness. Unsurprisingly, Rails application also go through growing pains as they mature. Models and controllers expand until small objects are extracted to keep them under control. The same happens with Rails views; they start out powerful and easy to use and slowly grow out of control. The views become hard to reason about and maintain. Views are also inherently hard to test, so they become the riskiest part of a Rails application.

Decorator

Decorators are added to contain the situation. Gems exist to help with this, but we don’t need them. SimpleDelegator is built into Ruby so we can make use of it like so:

class CommentDecorator < SimpleDelegator
  def gravatar
  end

  def timestamp
  end

  def author_name
  end
end

CommentDecorator.new(comment)

Decorators are great, and they help for a while. The problem is that they are tightly coupled to models. Models tend to describe big ideas in the system that are displayed in many different ways. Decorators, therefore, get bloated as they start describing numerous UIs.

View Component

Applying basic OOP principles we can break a decorator into smaller objects. Instead of a CommentDecorator we can build several components: CommentForm, CommentBox, CommentThread, ReactionButtons, etc. We don’t need a fancy gem to do this. A plain old ruby object will do:

class ViewComponent
  include ActiveModel::Model
  attr_accessor :context

  def render
    context.render(
      partial: "components/#{template_path}",
      locals: { component: self }
    )
  end

  private
  def template_path
    self.class.to_s.underscore
  end
end

The view component objects can be put under app/view_components and their templates can be placed in app/views/components/. The template is just a rails partial that gets a component local variable.

The view components will each inherit from the main ViewComponent class:

# object at app/view_components/comment_box.rb
# template at app/views/components/_comment_box.html.erb
class CommentBox < ViewComponent
end

# object at app/view_components/comment_thread.rb
# template at app/views/components/_comment_thread.html.erb
class CommentThread < ViewComponent
end

# object at app/view_components/comment_form.rb
# template at app/views/components/_comment_form.html.erb
class CommentForm < ViewComponent
end

We’ll add a helper to facilitate the rendering of a view component:

def render_component(component, props)
  component.new({ context: self }.merge(props)).render
end

Now anywhere in our views we can render a component with:

<%= render_component(CommentForm, {some: 'property'}) %>

View components are ideally minimal as they have a single and focused responsibility. This makes them easy to test and reason about. We can use a real rendering context if we wanted to in tests or mock it and do isolation testing.

Interactivity

View components implemented in Ruby are a good solution until interactivity is required. If for example, our user interfaces need to respond to mouse events then the Ruby classes become a dead-end. Vue.js or Backbone.js are excellent JavaScript libraries for adding interactivity on-top of server-rendered views. To pass properties from the ruby side to the JavaScript side, we just have to make sure they exist in the HTML data attribute:

<%= tag.div id: "element-id", data: { name: "Ahmed" }.to_json do %>
  <p>Component template here!</p>
<% end %>

const node = document.getElementById('element-id');
const props = JSON.parse(node.getAttribute('data'));

const component = new Vue({
  el: '#element-id',
  data: props
});

This is, in my opinion, a great solution for applications that just need a sprinkle of interactivity. Of course a component that is spread over four languages (Ruby, JavaScript, HTML, and CSS) becomes harder to test and contribute to. For new projects I recommend switching entirely to front-end components. Backbone.js, React, or Vue.js can be used to build both the template and behavior of complex UI components. This is a topic I want to explore more in the future on this blog.

Compose Software Like Nature Would

Wed, 04 Oct 2017 00:00:00 +0000

Inspired by biology background, I combine some ideas from functional and OO programming into a presentation about software design. I gave this talk at the OttawaJS meet-up group in September. The slides can be seen here.

Talk Summary

The only constant in software development is change. When our software cannot adapt, it turns into a big ball of mud. It becomes hard to hard to reason about and hard to change.

Living organisms, on the other hand, have the incredible ability to adapt to their environment. Over 3.5 billion years they evolved many different adaptations. For example, there are 400k species of beetles, and they live in diverse habitats. Some beetles feed on decayed matter while others prefer locally sourced, organic vegetation. Perhaps nature could be our inspiration for better software.

The conclusions of the talk are:

Resources

Gary Bernhardt - Boundaries
Dan North - Software that Fits in Your Head
Rich Hickey - Simple Made Easy
Jessica Kerr - Functional Principles for OO Development

Pure Functional Programming

Fri, 18 Aug 2017 00:00:00 +0000

Functional programming has a long history, with the first programming languages that use functions made in the 1950s. There has been a recent resurgence of the functional programming paradigm, so I think it’s important to be familiar with it.

There are a lot of concepts in functional programming – for example, first class functions, immutable types, lambda calculus, recursion, closure, currying, and monads – so it can be confusing. But at its core the functional paradigm is about one thing:

Pure Functional Programming is simply about avoiding side-effects.

Side-effects

When a program modifies state:

let count = 0 // starting state
const incrementor = () => { count + 1; };

Above is a function that causes a “side-effect” by changing the count variable outside of its scope.

When a program mutates data:

const array = [1,6,4,2];
const sorter = () => { array.sort(); };

The sort method mutates the array, so our [1,6,4,2] state is gone forever. The “side-effect” here is that we’ve broken any other program that relied on the order in array.

When a program depends on anything other than its arguments:

The examples above have an additional problem. The functions depend on count and array which are not passed in as arguments.

When a program interacts with I/O:

const myLogger = (output) => { console.log("Log:", output); };

A program that raises an error, writes data to disk, or prints something on the screen is causing a “side-effect.”

Problems with side-effects

A program that has side-effects is hard to reason about because it gives us no guarantees about what is going to happen. When a program depends on things other than its arguments it is relying on hidden inputs that might not be available at all. We can’t safely predict what these programs will do or even reuse them elsewhere because they are tightly coupled to their context.

These programs are also hard to test in isolation without excessive mocking and stubbing.

Avoiding side-effects: pure functions

Pure functions depend only on their arguments and return a value without causing side-effects. These functions will always return the same output given a specific input. For example:

const incrementor = (count) => { count + 1; };

const myLogger = (output) => { "Log: " + output; };

This second function is not interacting with I/O (console) anymore. This pure function transforms data into a form that we can later send to the console. When testing this code, we don’t have to mock or assert against console.log.

Pure functions are easy to understand, test, change, compose, and reuse.

Avoiding side-effects: immutable data

We’re safe inside of pure functions because we know our inputs and outputs. But what if the inputs are mutable (i.e., something outside of the function can change them)?

const array = [3,1,2];
const getFirst = (array) => { return array[0]; };
getFirst(array) // 3

array.sort(); // somewhere else, something mutated the array
getFirst(array) // 1

Our function is working fine, but it’s giving us an unexpected output. JavaScript arrays and objects are mutable, so we have to be very careful. Languages like Clojure and Elixir have immutable data structures, so this problem doesn’t happen.

Freeze Data

For primitive types like strings and numbers, we can rely on const because the values are immutable. Reassigning the variable name will raise an error.

const myName = "Ahmed";
myName = "Paula" // TypeError: Assignment to constant variable.

For arrays and objects we can use Object.freeze(). Going back to the example above:

const array = Object.freeze([3,1,2]);
const getFirst = (array) => { return array[0]; };
getFirst(array) // 3

array.sort(); // TypeError: Cannot assign to read only property '1' ...
getFirst(array) // 3

This technique doesn’t work for nested data types; for those we have to freeze each level recursively. MDN has an example of doing this or you can use the deep-freeze npm package which does the same thing.

We can’t change immutable data types, so we have to make a copy. Copying does come with a performance penalty, especially if we’re transforming a lot of data, so we have to be cognizant of that.

In ES2015 we can copy arrays with the spread operator, like so: newArr = [ ...prevArr ] and in ES2009 we can use newArr = prevArr.slice(). For objects we can use the spread operator in a similar way nextObj = { ...prevObj } or with ES2009 nextObj = Object.assign({}, prevObj)

Note that the above examples only do a shallow copy. Another example from MDN gives us a solution for deep clone that works for both objects and arrays: nextObj = JSON.parse(JSON.stringify(prevObj)).

Languages like Clojure and Elixir that have immutable data structures take care of this for you and do it in a very efficient manner. The Wikipedia page about persistent data structures is a good read.

Dealing with side-effects

Functional programming is ideal for computations. The pure functions always apply the same algorithm to inputs and will always give a predictable output. The goal is to push side-effects (persisting state, writing to disk, printing on a screen, making HTTP requests, raising errors, etc.) to the edges of our program.

One potential way of dealing with side-effects is to treat them as streams. The “outside world” is a stream you can read from or write to. Pure functions are composed and then finally at the edges of our program we connect to the outside “streams.”

Input |> (function_1 |> function_2 |> function_3) |> Output

Everything inside the parentheses is pure functional programming. |> is a pipe operator that unfortunately JavaScript doesn’t have. But there’s a proposal.

Reactive programming might be useful for dealing with asynchronous data streams. In the reactive paradigm, user interactions with a UI are an event stream.

A pragmatic approach might be to “eject” from the pure functional paradigm and go into Object Oriented Programming at the edge of the program. OOP is complementary to the functional paradigm because it can be used to rationally model the side-effects of our programs and hide their implementation details.

Object Oriented Programming Is Not About Objects

Mon, 07 Aug 2017 00:00:00 +0000

When I was introduced to Object-Oriented Programming (OOP), the focus was entirely on modeling our world using classes and hierarchies. Inheritance was taught immediately as a main concept. The problem with this is that Alan Kay coined the term OOP, and what we’re doing and teaching has nothing to do with what he envisioned.

I thought of objects being like biological cells and/or individual computers on a network, only able to communicate with messages… OOP to me means only messaging, local retention and protection and hiding of state-process, and extreme late-binding of all things. – Alan Kay

OOP is not about classes, inheritance or even objects per se. The important part is messages.

The metaphor

Biological cells

Living organisms are extremely complex yet built from tiny, relatively simple, building blocks. Trillions of cells make up a human being. Even smaller components make up these cells.

Cells have a half-life, meaning that they will eventually decay and die. Blood cells will live for about 100 days and then die. Other blood cells are created to take their place.

Cells have walls that isolate them from their environment; they communicate with each other through tiny channels.

Computer networks

Like a living organism, the internet is a collection of billions of computers. These computers will die off or disconnect, and the internet doesn’t even notice. Computers are isolated from each other and can only communicate with each other through a narrow protocol. TCP/IP, the protocol that connects all of these computers together, is ~10k lines of code yet lives forever and scales well.

Takeaway 1: Build Small Components

If we’re trying to model a problem space then making a person class makes no sense. A person is a collection of many components and they have many different roles. Classes will get you in trouble. Adding inheritance and hierarchies on top of classes is just trying to fit the world into a model you invented. Chances are you will get the classification wrong and will have to redo it or desperately patch it.

Taking our cue from biology and networks, we should build small components. The components can be objects, but they can also be processes (e.g. Elixir) or modules and functions. Individual components should do only one thing.

Takeaway 2: Compose Components Using Messages

Components should be isolated from each other. They shouldn’t know anything about the internals of others. Components should expose a small public interface to the world to say “here’s what I can do for you.” For example:

def construct_graph do
  data = DataFetch.get
  LineGraph.draw(data)
end

DataFetch and LineGraph respond to just one message, and we don’t know anything else about them. They each do one thing.

If we have to clean the data, then we can pass it through DataClean first.

def construct_graph do
  DataFetch.get |> DataClean.clean |> LineGraph.draw
end

Note: |> is a pipe operator – we’re just moving data to the right.

Let’s say that pie graphs would show this data better – then we can switch one component with PieGraph. If we need to render this information in another way, then we can change that last part as long as it responds to the draw message.

Dependency Injection

One mistake that we made above is using explicit dependencies. In the example above, our code relies on knowing DataFetch, DataClean, and LineGraph to do its job. We can instead “inject” these dependencies:

def construct_graph(data_fetcher, data_cleaner, grapher) do
  data_fetcher.get |> data_cleaner.clean |> grapher.draw
end

Now this component composes three parts without explicitly knowing about them. We can reuse this to build several different types of graphs or representations.

Pub-Sub

For more complex composition pub-sub might be useful. For example, we are selling books online, and after payment goes through we need to do several things. We need to send an order confirmation email, start preparing the book file, sign up the user to the book’s forums, etc.

All of these operations can subscribe to the order component. After payment goes through, the order component will publish/notify all subscribers. All of the subscribers will respond appropriately and do their unique operation.

Avdi Grimm has an example of using the observer pattern in a Ruby on Rails application.

Half-life and Testing

Like biological cells, we can replace these small components of code without breaking the system. We can more easily reason about them, and so we can refactor with confidence.

Components that have few dependencies and a small interface are easy to test. We can easily decouple them from slow operations like the database or HTTP and write fast tests that focus on their behavior.

Bear in mind that while the isolation tests check that each component works, we need to do end-to-end testing to prove that it all works together.

Inheritance is not evil

Inheritance is sometimes useful, but we have to be careful how we use it. Prefer composition unless you’re sure you have a good use case for hierarchies. When you use inheritance remember to keep it shallow (don’t subclass a subclass). Subclasses should inherit everything from their parent.

Object-Oriented Programming is essentially one simple idea: build small things and compose them with messages. We can do this in any programming language. There is no reason to complicate matters.

React.js: The Hard Parts

Sat, 22 Jul 2017 00:00:00 +0000

Getting started with React is easy. You don’t need anything fancy – just use codepen.io and off you go. React doesn’t need to be part of a single page app, you can progressively add it to existing apps. The API for React is mostly just JavaScript concepts. The documentation is excellent, and there are a lot of helpful free resources available. JSX can be awkward at first, but it’s just HTML for the most part, so it’s easy to pick up.

Most of the concepts in React are manageable. The hardest part, in my opinion, is state management.

What is “state”?

Program state has a long history in computer science, but essentially it’s just the “condition” that our program is in. If we’re rendering a tweet, then its state will be things like contents, the number of likes, the number of retweets, whether it’s expanded or collapsed, etc.

In traditional server-rendered apps we don’t have to worry about state changes. If a user interacts with your application or refreshes the page, then we’ll look up state at that moment and rebuild the page.

In dynamic apps, like ones built using React, state change has to be dealt with immediately. If a user clicks “retweet” then the rendered tweet needs to change instantaneously.

If your app is very dynamic (hence React) then you’ll be juggling a lot of states. To complicate things even further, what if someone from a different computer clicks “retweet” – how do we update state for everyone looking at that tweet? Moreover, some states are user-specific and possibly not saved at all, for example, whether navigation on the page is fully open or collapsed.

Facebook suggested a pattern called “flux” that can be very useful for managing a UI’s state. There are three main points:

single source of truth
top-down data flow
state is changed through actions

There’s a library called Redux that implements this pattern. You might not need Redux though, especially for smaller applications. The following describes one way to manage state without using Redux.

Single source of truth

Managing state can get complicated if each component has some state. The users will start to experience inconsistencies. For example, in an email client, the header shows that you have two unread messages while the inbox itself is empty. One solution to this problem is to have a single place where we store state. This “store” is the single “source of truth” in the application.

Keeping state centralized is a concept that we have embraced on the server-side by using one database so doing the same for the client-side seems reasonable. As a compromise, especially in the prototyping stage, we can use “container components” instead of a single store.

Container components handle state for many child components.

Top-down data flow

The child components are stateless functions and get all of their data as properties from the container (parent) component. These are simply visual components.

The above is called a stateless functional component. These functions don’t have state or life-cycle methods. React encourages their usage because they’re easy to test, compose and reuse.

State is changed through actions

Functions are passed down to the child components to handle actions. Interaction with the components, like a mouse click, trigger these functions to update state. For example to implement retweets:

When the state is updated, the props will change too and render the child components again.

In summary

Your application might be composed of multiple container components. As the app gets more complex, with this approach, it will be easier to graduate to a solution like Redux.

properties flow down; actions flow up

Front-end Web Development in 2017

Mon, 10 Jul 2017 00:00:00 +0000

Web development appears to have a furious rate of change so keeping up can be overwhelming. In reality, though, stable changes don’t happen that often. To put things into perspective: the hottest JavaScript framework right now, React.js, was created four years ago. jQuery is ten years old and is still on 70% of the top 10k websites. One sane approach is to avoid the hype train and stay on firm ground. Sometimes it’s a good idea to watch the framework jostling from a distance. That said, front-end web development has reached an unprecedented level of maturity, and there’s a lot of warranted excitement.

Mobile First

jQuery was created in 2006 to address cross-browser incompatibilities. For example, Internet Explorer has been a huge issue for a long time because of its lack of support for many critical JavaScript and CSS features. Microsoft has dropped support for I.E. 8, 9 and 10. Today these old browsers, combined, have less than 1% of the browser market share. All of the top JavaScript frameworks (React, Angular, Ember) still support I.E. 9. 1% of two billion active Facebook users is a lot. For the rest of us, it’s safe to drop support and not look back.

More interestingly, mobile has overtaken desktops in browser share. Google is doing mobile first indexing. Ethan Marcotte’s article about responsive web design from 2010 is still very relevant.

The internet is fragmented. We are always going to have to build our websites and apps for different platforms and browsers. Integrating manual and automated browser testing into our process is an excellent idea. It’s also prudent to use caniuse.com to find out what we can safely use across browsers.

JavaScript Like It’s 2015

JavaScript is the most commonly used programming language. I firmly believe that learning it is the best thing a web developer can do for their career. I highly recommend the book You Don’t Know JS for learning the language. The language itself is an implementation of a standardized specification called ECMAScript (ES). Nearly all of web browsers (~98%) have full support for 2009’s ECMAScript specification (ES5).

ECMAScript 2015 has a lot of great features, but the browser support is patchy. Not to worry though because you can write in ES2015 and then use Babel.js to compile the code to ES5. Learning to use these new features is easy thanks to the Babel.js guide.

JavaScript runs outside of the browser using Node.js. Node is extremely popular and its package ecosystem, npm, claims to be the “largest ecosystem of open source libraries in the world.” There are many versions of Node, and they have partial support for features from ES2015, ES2016, ES2017, etc.

Writing ES5 is acceptable, but ideally, we write in ES2015 and let Babel.js take care of the rest. Airbnb has an excellent JavaScript style guide that can help you write good code. I recommend running your JS code through a linter like ESLint to catch common errors. Flow is another useful tool; it’ll type-check your JS code to find bugs early on.

Components

I thought of objects being like biological cells and/or individual computers on a network, only able to communicate with messages. – Alan Kay

Writing software is relatively easy, maintaining it is hard. That is why most programmers have converged on the idea of writing small components (objects, functions, etc.) and carefully composing them. The complexity of the software decreases because each component “can fit in your head,” and you can reason about it. These loosely coupled components can be replaced more quickly, with more confidence, and with fewer side-effects.

The front-end JavaScript frameworks have all embraced the same, decades-old, idea. You write components for UI elements and then loosely combine them together to build an application.

Components let you split the UI into independent, reusable pieces, and think about each piece in isolation. – React.js

Everybody loves React

Today, Angular is the JavaScript framework that has the biggest adoption, although React.js has the greatest momentum. Developer surveys in 2017 show that React.js is the highest rated library as developers seem to enjoy using it. If you are interested in learning a library/framework this year, then I highly recommend React, especially because the hiring trends are strongly in its favor.

React.js leverages ES2015, components and powerful build-tools to help you develop dynamic web applications. It is conceptually simple. You create components, and then when there are state changes, React will redraw the component. This is in contrast to the more bug-prone manual changing of specific elements on the page that we had to do with jQuery.

If you want to learn React then I highly recommend doing the following:

Learn JavaScript well.
Learn ES2015, especially arrow functions, classes, and modules.
Build simple components with React.
Make a full app with React.

Long Hiatus

Sun, 02 Jul 2017 00:00:00 +0000

I haven’t posted on this website in a few years. The difficulties I have experienced in getting going again have made me appreciate even more the people who work full-time and still manage to contribute to the software community through blog posts, videos, and open source code. I want to write more, and actually publish. To get things started off, I would like to share some of the interesting experiences from the last few years as a full-stack software developer.

Open Source

My main open source contribution over the past few years has been an Ember.js component. It’s a small project but has been a great learning experience. Many people download this addon every day, so it keeps me motivated to keep it updated. The component has had 14 contributors so far which is encouraging; it’s nice when people get involved. Someone even made a screencast explaining how to use the component, so that was a thrill to watch. It feels gratifying to know that something you’ve done is helping others, even if it’s in a minor capacity.

Recruiting

Last time I was looking for a job I spent months researching companies, applying, and interviewing. The pool of employers (especially remote ones) seemed very small. I had the impression that most companies had their pick of dozens of qualified people. After being involved in the hiring process at my current workplace, it’s clear that that’s not true. Hiring a software developer who is a good fit for the company is very hard. The amount of risk involved in the hiring process is huge because it takes months to hire and onboard a new person. Even senior developers have a tough time making meaningful contributions right away so you could potentially spend many months before you find out that they are not a good fit. I certainly have a lot of empathy with companies now and respect the hiring process more.

Focus

Building software isn’t too difficult. Building great software is in my opinion quite hard. A lot of the difficulty comes from having the discipline to focus on one small problem space. Everyone loves new features, so it’s easy to keep adding more and more. Removing features takes a lot of courage, so it rarely happens. Over time you end up building software that does everything but badly. This problem is especially acute when there is no unifying vision, and many viewpoints push and pull the project in different directions.

Ideally, a project has a strong vision and real actionable data that helps steer the vision. The data about how people are using the app can help the team experiment, iterate and perhaps even remove features to simplify the design.

Project Management

Over the past two years, our teams experimented with many different project management techniques. Usually, this is prompted by perceived low productivity, as if adopting a new process will fix profound organizational issues. My opinion about project management is probably controversial, but it’s pretty simple: any process will do, and the simpler, the better. Adopting agile isn’t going to make your project more attractive, nor is it going to make your codebase easier to work with.

The agile manifesto misinterpreted:

“Individuals and interactions over processes and tools” somehow translates as “let’s use a process with a cool sounding acronym (SCRUM!), have daily meetings, estimate everything, and install complicated tools for managing this whole process”. The work ends up being chopped up into tiny little pieces and fed into the developer assembly line. Productivity goes up in the short-term at the cost of quality. Over the long-term productivity goes down as developers have less and less control over their work. Conveniently for managers, now every developer has a number over their head – the one they were forced to estimate.

“Working software over comprehensive documentation” sounds great if you follow the remaining two statements from the agile manifesto: “Customer collaboration over contract negotiation” and “Responding to change over following a plan.” If the organization as a whole remains invested in contracts, and scales back production after the software is “delivered,” you are, in short, delivering crappy software.

Ideally, the right people are hired, and they’re trusted to get the job done. The team needs to make meaningful decisions and have a lot of input over the direction of the project. A simple process with continuous delivery is all you need.

Estimation vs. bargaining

Estimation starts off as a “rough guess” because people need to know how much the software will cost. The healthy response to a high estimate would be to reduce scope, but that doesn’t always happen. Some people, usually out of desperation, end up bargaining with the developers. “Can you do this in less time?” is always asked and undisciplined developers, eager to please, will say “I’ll see what I can do”. Of course, the result is that software gets delivered faster by skimping on the quality. First, tests go out the window; next, refactors and quality; then UI’s go missing, and so on. What developers are doing is writing technical debt. This debt has to be paid one day – with compound interest.

Craftsmanship

Solving problems as a software developer isn’t that hard. We can deliver a “working solution” relatively quickly. If you’re working with developers, you have to ask yourself whether you want the “working solution” or a finely crafted solution that will pass the test of time. Do you want your users to grit their teeth and suffer through it or do you want them to have a smooth and memorable experience?

To produce a great product you need talented people working under reasonable expectations. The company needs to have a culture of craftsmanship.

Ideally, there’s a lack of emphasis on “process” and developers have the freedom to work on whatever inspires them. One day it might be refactoring a major piece of the code that is causing trouble. Another day it might be introducing a useful new feature or tool. The company can deliver a lot of value if it learns how to direct the passion and inspiration of the developers.

Companies need to encourage developers and reward them for standing their ground about high-quality software. Testing should be a requirement, not a “nice to have.” User experience should be paramount, not an afterthought. Code reviews should have an extremely high bar without comments like “I have to ship this today so we’ll fix it later.”

Designing & Building RESTful JSON APIs

Wed, 27 Aug 2014 00:00:00 +0000

Yesterday I gave a talk at Ottawa’s Ruby Meetup. The talk was about designing and building Web APIs. The slides and a recording are below, enjoy!

Ahmed Omran

Compose Software Like Nature Would - RubyConf 2024

Talk Summary

Resources

People first

Manage with people first in mind

Making yourself indispensable to your team

Presence

Ownership

Software Design

Delivering solutions

Rails View Components

Decorator

View Component

Interactivity

Compose Software Like Nature Would

Talk Summary

Resources

Pure Functional Programming

Side-effects

Problems with side-effects

Avoiding side-effects: pure functions

Avoiding side-effects: immutable data

Dealing with side-effects

Object Oriented Programming Is Not About Objects

The metaphor

Takeaway 1: Build Small Components

Takeaway 2: Compose Components Using Messages

Dependency Injection

Pub-Sub

Half-life and Testing

Inheritance is not evil

React.js: The Hard Parts

What is “state”?

Single source of truth

Top-down data flow

State is changed through actions

In summary

Front-end Web Development in 2017

Mobile First

JavaScript Like It’s 2015

Components

Everybody loves React

Long Hiatus

Open Source

Recruiting

Focus

Project Management

Estimation vs. bargaining

Craftsmanship

Designing & Building RESTful JSON APIs

Video recording

Slides

Code

Questions?