High Level System Analysis and Design with Domain-Driven Design

2026-04-06T00:00:00+00:00

Photo by Zed Jensen, 2022.

Domain-Driven Design is an approach to software development that focuses on, as Eric Evans puts it, “tackling the complexity in the heart of software”. And what is in the heart of software? The business domain in which it operates. Or more specifically: a model of it, made of code. That is, the code that implements the business logic that comes into play when solving problems within the realm of a particular business activity.

DDD is not just about writing code though. It’s a whole methodology that touches on business needs, requirements gathering, organizational dynamics, high level architectural design, and lower level patterns for implementing software intensive systems.

As a result, DDD offers a treasure trove of concepts, patterns and tools that can be applied to any software project, regardless of the size and complexity.

In this series of blog posts we’re going to explore many aspects of DDD. We will be following the structure laid out by Vlad Khononov’s excellent book on the topic “Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy”. So you can think of this series as a summary of that book. An abridged version that can serve as a review for anybody who has read it; but also as an entry point for people who are new to DDD.

High level system analysis and design with Domain-Driven Design

Section 1. Analyzing business domains

It is a well understood notion that before writing code, we need to understand the problem we’re trying to solve. DDD is consistent with this notion and argues that developers need to, first and foremost, gain an understanding of the business that the software is being built for. To this end, DDD relies on three concepts: domains, subdomains and domain experts.

Domains and subdomains

In simple terms, the domain of a business is what it does, its area of activity. For example, Starbucks is in the business of making coffee, Ford is in the business of making automobiles, AMC is in the business of movie theaters.

Of course, analyzing a business as a single integrated whole can be unmanageable. That’s where subdomains come in. Subdomains are the different divisions within a domain. Starbuck’s domain for example, is making coffee. But there are many smaller parts that make up that business and allow it to be successful. There’s of course, the subdomain of coffee preparation. But there’s also real estate management to find and secure good locations, there’s inventory management and logistics, there’s marketing, there’s human resources, etc. All these are the subdomains that make up the overall business of Starbucks.

Depending on the business and on the project, these will vary greatly in granularity. And you can also decompose subdomains further and discover new fine-grained subdomains nested within more coarse-grained ones. The sizes and nesting levels can be very different from business to business, so it can be difficult to clearly delineate where a subdomain ends and another one starts, which activities belong to one or the other. One good rule of thumb to keep in mind is that generally, subdomains encapsulate a set of coherent, closely related use cases. That is, use cases that involve the same set of closely related actors, business entities and/or data.

And finally, we have domain experts. As the name suggests, these are the people within the organization who have intimate knowledge of the business, or certain areas of it. They are the subject matter experts. Usually they are the ones who identify the problems and come up with requirements. Developers need to rely on domain experts to gain the necessary understanding to be able to produce useful software solutions.

So, when approaching software projects, DDD suggests that developers work closely with domain experts in order to learn from them about the business domain and subdomains. After all, it is their mental models and understanding that will be modeled and implemented in code.

Types of subdomains

With the help of domain experts, developers can identify subdomains, understand their business value and how they fit within the overall business strategy. This is very important because it helps making some initial architecturally significant decisions. Namely, the general approach to solving the problems in the subdomains, how much to invest, how to organize development teams, etc. The main objective in this analysis stage is to identify the subdomains and whether they fall into one of three types: core, generic, and supporting.

Core subdomains are the activities of the business with highest value. The ones that confer differentiation in the market and a competitive advantage. They are the business’ raison d’être. For example, for Google, their search engine is a core subdomain. For Ford, their automotive engineering area would be a core subdomain. Core subdomains are generally the most complex parts of the business. They are constantly evolving and improving, and the company is compelled to invest heavily in them.

Generic subdomains are also very complex. However, they are not business differentiators. Instead, these are the areas of the business that all organizations handle in the same way. Think accounting, a ticketing system, an online storefront. There’s no pressure to innovate in these areas, so the solutions are very stable and evolution is slow.

Supporting subdomains on the other hand, do not provide any competitive advantage, nor are they very complex. They are however, necessary because they support the core business activities, and are fairly unique. The solutions to problems in these areas usually take the form of CRUD or ETL oriented activities. Imagine for example populating a data warehouse, translating transactional business data into a format appropriate for analytics and business intelligence in a manufacturing corporation. Or maybe the digitization and storage of a registry of court documents for a law firm. These are behind the scenes activities that support the organizations’ main businesses, but their business logic complexity is not high, and they don’t really represent big selling points for the company.

It’s worth noting as well, that there may be subdomains where software solutions are not appropriate, even if they are highly complex core subdomains. They are still part of the business so it’s worth identifying and considering for high level architectural design decisions. If anything, to know what parts of the business the planned software system should and should not focus on. You could have a restaurant, for example, who prides itself in having the best desserts in the city. For their business, the recipe development activities constitute a core subdomain. This is dependent on the art and craftsmanship of the chefs. Not an area in which software solutions could help a whole lot.

It’s also worth noting that, just as organizations’ business strategies are dynamic, so too can be their subdomain distribution. Today’s generic subdomain can be tomorrow’s core subdomain, and so on. For example, imagine a big retail store chain that, up until now, managed its inventory in an industry standard way. But it has grown so much that the standard way of doing things has become a bottleneck for them. So they design a new procedure for highly efficient inventory management, and that gives them an edge against competitors. Inventory management started as a generic subdomain for them, but due to an ever evolving business strategy, it became a core subdomain.

The knowledge of subdomain types can also help the analysis when dividing the business and discovering subdomains. If you find yourself recursively finding more and more fine-grained subdomains from already identified ones, a good time to stop recursing is when you find that a generic or supporting subdomain, when broken down, reveals only new finer-grained generic or supporting subdomains. The reasoning for this is simple: this analysis activity is most valuable when trying to identify core subdomains. When there are no more core subdomains to be found within a particular area of the business, then it’s probably not worth it to keep digging deeper.

Here we have an example of a hypothetical help desk system subdomain, part of a customer service subdomain, being decomposed and revealing that it only contains generic subdomains.

In summary, these are the main characteristics of the three types of subdomains:

Core subdomains have high complexity, provide competitive advantage, and change and evolve frequently.
Generic subdomains have high complexity, do not provide competitive advantage and change overtime, although at a slower pace than core subdomains.
Support subdomains have low complexity, do not provide competitive advantage and are the slowest to change.

This is where each type of subdomain fall when considering their business logic complexity and business differentiation.

Using subdomains to make strategic decisions

Like I’ve already alluded to, armed with this knowledge, DDD practitioners are ready to start making some higher level architectural decisions. Depending on the type of subdomain that a problem belongs to, DDD has specific prescriptions on how to handle the implementation of software solutions for them.

When working on core subdomains, that’s where we want to make the biggest investments. We deploy the most advanced engineering tools, patterns and practices. This is to make sure that the software is efficient and high quality, and also easy to maintain and evolve. This is necessary because core subdomains have to evolve rapidly by nature, if the business is to maintain competitive advantage. Software solutions that operate within the context of core subdomains have to be implemented by high skill and high trust teams. Either in-house, or via trusted development partners, working hand in hand with domain experts.

Problems in generic subdomains, by nature of their business logic being very complex but also very common, are likely to have already been solved. For these types of problems, DDD recommends against implementing custom software, and instead buying and/or adopting tried and true, industry standard, off-the-shelf solutions. Their implementation and integration can be outsourced or handled by less specialized or skilled teams. The change management of these solutions is simple, as they get delivered generally via patches and updates.

For support subdomains, whose business logic is generally simple but uncommon, it is less likely that off-the-shelf solutions would be available. So software addressing problems in these subdomains will most likely have to be implemented as custom solutions. Due to their low complexity though, they can be easily outsourced, or handled by more junior team members. They can also be handled with RAD, low-to-no-code technologies, since often times they are little more than ETL and pure CRUD applications.

Here’s a table to summarizes the differences between the types of subdomains:

Type of subdomain	Core	Generic	Supporting
Competitive advantage	Yes	No	No
Complexity	High	High	Low
Rate of change	High	Medium	Low
Implementation	Custom development	Buy/adopt off-the-shelf	Custom development
Team composition	In-house/partners	Can outsource	Can outsource
Skill level	High	High/regular	Low
Investment	High	Medium	Low
Problems	Interesting	Solved	Simple

Section 2. Discovering domain knowledge

After identifying the business domain and categorizing the various subdomains that compose it, we have a bird’s-eye view of the business. This is good enough to get started and make high level architectural decisions of potential software solutions to problems within these domains. To actually build the software though, we need much more than that. In order to gain a thorough understanding of the business logic, and be able to eventually model and implement it in code, DDD proposes the ubiquitous language as a tool.

The ubiquitous language

The ubiquitous language is DDD’s tool for knowledge sharing, effective communication and software modeling. In simple terms, the ubiquitous language is the language of the business. It’s the language that domain experts use on a day to day basis to talk and reason about the business.

For a software project to be successful, it’s essential that engineers and stakeholders understand each other. They have to be aligned when it comes to the meanings of the core concepts of the business domain. That’s why it’s so important that everybody uses the ubiquitous language for all project related communications, requirements, documentation, face to face discussions, and even code itself. It all needs to share the same language.

Engineers will need to interact with domain experts in order to learn about the business domain and its rules. They need to acquire the necessary knowledge that allows them to implement these rules in the software. During these interactions, they converse using the ubiquitous language. However, the knowledge transfer is not always strictly unidirectional. Yes, engineers have to learn from the domain experts. But also, through conversations and questioning, engineers can help domain experts deepen and flesh out their own understanding about their domains.

A classic example of this is when domain experts focus too much on the “happy paths” of given business processes. Then, through discussions with developers, on account of the inherent precision that software demands, they are forced to consider more edge cases, better specify ambiguous terms and fill out gaps in their understanding.

This deepening of knowledge feeds back into the ubiquitous language and improves it. Making it more insightful and more precise. This means that, throughout the life cycle of a project, the ubiquitous language should keep evolving, expanding and refining. This allows it to continuously improve as an effective model of the business domain, for the problem that it’s trying to solve. Indeed, just like code is a model of the business domain, so too is the ubiquitous language.

A classic pitfall in software projects is a manner of communication and knowledge sharing where developers are various steps removed from the domain experts. Consistent use of the ubiquitous language addresses this.

The ubiquitous language as a model of the domain

Through consistent use of the ubiquitous language, developers are able to obtain a deeper understanding of the domain, the problems we’re trying to solve, the reasoning behind the requirements and the mental model of the domain experts. This allows the construction of effective software solutions, with deep business insight, that go beyond simply translating requirements into code. If the implementation models the business domain effectively, there is potential for it to evolve with the business and better adapt as requirements change; and we reduce the risk of missing edge cases that may not be obvious to domain experts.

Under DDD, developers and domain experts develop the ubiquitous language, which then informs the implementation.

Effectively, when we build a ubiquitous language, we’re building a model of the domain. A model that reflects the relevant business entities, their behavior, and relationships. A model that will be eventually implemented into code, but also a model that needs to be understood by all stakeholders, regardless of their technical level. So it needs to be precise and rigorous, but also understandable. As such, in order to be useful, the ubiquitous language needs to respect certain restrictions:

It must not include technical jargon like programming languages, constructs or frameworks; nor mention specific system structures like database tables, servers or programs. It is the language of the business and it needs to be understandable by non technical folks.
It must avoid using the same term for different concepts. In conversation with humans, a lot of the meaning is extracted from the context. In software, not so much. Just like you can’t have two classes with the same name within the same namespace, the ubiquitous language cannot allow such ambiguities.
It should also avoid using different words for the same concept. The classic example for this is words like users, accounts, customers, visitors. They all refer to closely related concepts which might actually have differences. The problem with these overlapping terms is that those differences are obscured by the notion of them “being the same” and being used interchangeably. For usage within the ubiquitous language, it’s best to be precise and clearly delineate terms and definitions. Eliminate what’s redundant, be strict with definitions.
It should avoid including extraneous details. Just like code needs to include only what’s needed to solve the problem at hand and nothing else (in order to avoid accidental complexity); the ubiquitous language must not be polluted with details from outside of the area of business activity that it represents. That can create confusion and unnecessary cognitive load.

The ubiquitous language represents a unified model of the domain. This is in contrast to a more traditional process where domain knowledge gets “translated” multiple times before turning into code.

Tools for capturing the ubiquitous language

The Agile Manifesto declares: “Individuals and interactions over processes and tools”. And of course, when it comes to the ubiquitous language, direct interaction and conversations between engineers, domain experts and other stakeholders reigns supreme. That’s when it can be most useful. It can also be useful, however, to capture the ubiquitous language in documentation and even in runnable form.

A glossary of terms is a great asset for keeping a ubiquitous language. A wiki is a good place to put this. Definitions for key concepts in the business like entities, processes and rules can be captured here. The only caveat is that documentation is static by nature, while the ubiquitous language is continually evolving. So, great care needs to be taken to keep the wiki updated at all times to reflect the latest and most complete understanding of the domain. This should not be relegated to or gate-keeped by only certain people; it should be a team effort where everyone contributes.

An automated acceptance tests suite, written using Behavior Driven Development frameworks, like Cucumber, is also a great way of capturing the ubiquitous language. The advantage of these tests is that they are written in plain human-readable language, not code. And while it may be far fetched to think that non technical domain experts would be capable of writing and maintaining such tests, they certainly can read and understand them, which is a great boon. These tests speak the language they understand: the language of the business.

This is what Cucumber tests look like.

By nature of being executable and tied closely to the implementation code, there is less chance that they become out of date. This can happen more easily with static documentation written in a wiki. The disadvantage is that they require much more effort. But for the right kind of project, one where business logic is very complex or the scope is very wide, they can be very well worth the cost.

Section 3. Managing domain complexity

We can attempt to model an entire business domain with one big ubiquitous language, but sometimes that’s impossible. Especially so for businesses of a certain size, you will inevitably find inconsistencies and conflicts between the mental models of different domain experts. The simplest example of this scenario is when different experts from different areas of the organization have the same word to describe different concepts. Or when they look at the same business entity with different levels of detail.

When the different mental models are valid, and these inconsistencies are legitimate and cannot be reconciled, the solution is to follow the divide and conquer principle and decompose the language into separate ones, each one working within its own bounded context.

Simply put, a bounded context is the context within which a ubiquitous language, and the model it represents, operate, have meaning and are useful. Sure enough, just like a domain can be divided into subdomains, a ubiquitous language can be decomposed into smaller languages, each with its own context, to model different parts of the business. While we can attempt to capture an entire business domain with a single model, this is not advisable in the case of complex systems. It’s better to split up the model into smaller, more precise ones, tailored to work on specific problem domains.

Reasons for creating bounded contexts

Like mentioned before, different domain experts having conflicting mental models is a clear indication that a division in the model needs to happen. However, that only tells us half of the story. There are other indicators that point to when and where further division should happen:

First of all, there is of course, size. Size by itself is not a deciding factor, but it is something to consider and balance. Fewer, bigger models can help keep the overall environment simpler, but if they become too big they can become unmanageable and prone to corruption. A higher number of smaller models keep cognitive load low, but you run the risk of exploding integration and management complexity. The better principles to keep in mind here are coupling and cohesion. Beware of separating closely tied use cases, that deal with similar actors, entities and data.

System-level nonfunctional requirements also play a role in dividing a model into separate bounded contexts. For example, you might need to decouple the life cycle of several software components. Have them be developed, evolved, versioned and deployed independently. You might also need them to scale separately. You might even need to use completely different technology stacks, whatever is appropriate for the task at hand. This means that bounded contexts generally get implemented as individual services and/or applications. That is, as individual runtime components.

The organization’s composition also plays a role when designing bounded contexts. The general rule is that a given ubiquitous language, the model it represents and the bounded context is lives in, must be owned by a single team. In software, high ownership, cohesion and consistency are desirable traits. Having a single team own and maintain a particular component foments these. Single ownership also helps reduce communication overhead, and prevents people from stepping on one another’s toes. Of course, a single team can own multiple bounded contexts, what cannot happen is one bounded context being owned by multiple teams.

Indeed, in bounded contexts, we have the tools we need to make strategic decisions related to the decomposition of software systems into architecturally significant components or modules. With bounded contexts, we are able to specify the physical and ownership boundaries of these components.

Bounded contexts vs subdomains

Bounded contexts and subdomains are closely related concepts, but there’s one key distinction: subdomains are discovered, while bounded contexts are designed. Subdomains are useful because they help us understand the business strategy. Splitting the business domain into smaller problem domains is useful because it can break down a complex whole into smaller and more manageable parts.

Depending on the situation, it is certainly possible to end up with a set of bounded contexts that align one-to-one with the business subdomains. However, this is not mandatory. We can develop a solution with a single bounded context that spans multiple subdomains; the same way that we can decompose the problem into many bounded contexts, some of which operate within the same particular subdomain.

Bounded contexts are closely related to subdomains, but aren’t tied to them. They are flexible and can be organized in many ways.

Each bounded context becomes a separate major architectural component. That is, a (micro) service, a project, an application. When we have a component that spans multiple subdomains, programming language organizational structures like namespaces or modules can be used to logically separate the subdomains within.

Section 4. Integrating bounded contexts

For a system to function, its components need to interact with each other. So, once we have decomposed the problem domain into separate bounded contexts, we need to decide their relationship and integration strategies. This need for interaction between them implies that there are touch points between bounded contexts. We call them contracts.

These contracts are necessary because each bounded context contains its own version of the world. That is, its own model and ubiquitous language. In order to integrate, some level of translation needs to happen. They need to be adapted to one another. The contracts define these adaptations.

Domain-Driven Design offers various patterns that are useful for defining contracts between bounded contexts. The decision to use one pattern vs the other depends greatly on the nature of the teams tackling the project. Depending on the teams’ relationship, we can put the patterns in one of three categories: cooperation, customer-supplier, and separate ways.

Integration patterns are determined mainly by the level of cooperation between the teams that own the interacting bounded contexts.

Cooperation patterns

When the components that need to interact are owned by teams which are in close communication, work well together, and whose goals are aligned, cooperation patterns can be applied.

If the teams meet these criteria, a partnership model can be implemented. This is where the integration is managed in an ad-hoc manner. Both teams work together to define the API through which their components interact and that’s that. Whenever changes happen on either side, the other team learns about it quickly and adjusts their code right away. Continuous integration is a great tool here, as breakages are immediately apparent, closing down the feedback loop.

Sometimes, when different bounded contexts need to implement the same functionality, it makes more sense to develop this functionality once and package it as a reusable library, or a sub-module within a shared repository. This is what DDD calls a shared kernel. A shared kernel is effectively a bounded context of its own, one that is statically linked to other components and implements the logic that others depend on.

A shared kernel is its own bounded context, but also “belongs” to multiple other bounded contexts.

The shared kernel integration pattern needs to be used carefully though, as it creates tight coupling between the components that use it. If the involved bounded contexts are owned by different teams, then this shared kernel that emerges violates the DDD principle of bounded contexts having single-team ownership. This is something to watch out for, as bad team synergy can produce problems during development and maintenance.

When using a shared kernel, the quality of the communication and the coordination between the teams has to strike the right balance: when they aren’t strong enough to support a partnership model, but not so weak that the shared kernel would become more trouble than it’s worth.

The alternative to a shared kernel is the duplication of the logic across multiple components. When deciding whether to apply this pattern, the costs of duplication vs coordination need to be considered. That is, the cost of implementing the same logic within multiple components and its subsequent changes, vs the cost of changes in the shared kernel propagating into dependent components and coordinating with the owners of each. When it is cheaper to just duplicate the logic, shared kernel should not be applied.

This means that complicated models that change frequently, like those of core subdomains, are good candidates for shared kernel. Shared kernels allow complexity to be encapsulated and exposed through stable contracts. This means that frequent changes are easier to contain. Frequent changes in logic that’s highly complex and also repeated in multiple places, quickly becomes much more expensive to maintain.

Another good scenario for applying a shared kernel is when refactoring a legacy monolithic system into more separated modules. The legacy system can become the shared kernel during the time that modules are being extracted from it but not yet fully decoupled.

Customer-supplier patterns

Customer-supplier patterns establish a relationship between components where one (the provider, who is “upstream”), provides a service to another (the consumer, who is “downstream”). These types of patterns emerge when the teams who own the involved bounded contexts are not in close collaboration and have their own independent goals.

One form of customer-supplier integration is the conformist pattern. This happens when the supplier defines the integration contract/API, using its own language, concepts and model, and the consumer accepts it. This can happen when the upstream service has a well established or industry-standard model. Or maybe the model is “good enough” for the consumer to interact with directly. Organizational politics may also be a reason for this type of integration, where there is an imbalance of power favoring the supplier’s team, and they get to impose their model or can’t be bothered to adapt it.

Sometimes, the consumer won’t accept the supplier’s model. In that case, an anticorruption layer can be created. An anticorruption layer is implemented by the consumer and translates the supplier’s model into its own. This allows the consumer to use the supplier’s service without polluting its model with extraneous concepts.

Anticorruption layers can be good solutions for the following scenarios:

When the consumer represents a core subdomain. The consumer is solving hard and interesting problems, so it’s best to protect its model with the ACL.
When the supplier’s model is messy and inconvenient. The ACL can protect the consumer’s model from having to contend with a mess of extraneous concepts.
When the supplier’s contract changes frequently. The ACL can protect the consumer from those changes, encapsulating them, allowing it to be less volatile.

A third pattern represents an anticorruption layer of sorts, only built on the supplier’s side. DDD calls this the open-host service pattern. Here, the upstream service comes up with a new language, separate from its own, tailored to its consumers’ convenience, and exposes that as its contract. This public protocol is called a “published language”.

An open-host service provides a protocol for consumers to interact with. It can also support multiple versions of this protocol simultaneously.

An open-host service applies to similar scenarios as an anticorruption layer. Decoupling a service’s internal model from its integration model frees it up for continuous evolution without fear of breaking its consumers. Another advantage of this is that multiple versions of the published language can be exposed, affording clients options on what to support and gradually migrate if they so choose.

Separate ways

Sometimes, the right decision is to not integrate at all. I alluded to this outcome back when discussing the pitfalls of the shared kernel. Sometimes duplication, in spite of how bad it smells, may be the most cost effective solution to a given situation. So the teams go their separate ways.

This can happen when the involved teams cannot collaborate effectively for whatever reason. It could be due to geographical, timezone, or organizational issues.

This can also be a good solution when the repeated logic belongs in a generic subdomain, and it’s easy to integrate. For example consider a logging framework. Exposing that kind of functionality in a service for others to consume, in most cases would be much more trouble than just including some third party library or package.

It may also be that the models being integrated are just so different that they are fundamentally incompatible. It may be cost-prohibitive for collaboration or customer-supplier patterns to be applied; and duplication again, is cheaper.

Going separate ways can be dangerous when we’re talking about core subdomains though. So we have to tread carefully in those scenarios. Remember that models that represent core subdomain should be implemented in the most effective and efficient ways, with few shortcuts and minimized technical debt.

The context map

The context map can be a useful tool for high level design as it plots all the major bounded contexts (i.e. modules, components, subsystems) that we’ve designed and their interaction patterns.

Here’s a context map which captures the various bounded contexts that compose a big system and their interactions. The arrows point to the upstream component in the relationship. “ACL” denotes an anticorruption layer and “OHS” represents an open-host service.

Of course, they can also offer valuable insight into organizational dynamics, as team composition and relationships with others are intrinsic parts of the discussion when talking about bounded contexts. For example, it can show teams that prefer to collaborate closely or at a healthy distance. I can also show problematic components, which are surrounded by anticorruption layers or have had their ties completely cut via a separate ways approach.

As with any document, they run the risk of becoming stale as the system evolves. So it should be a team-wide responsibility to keep it up to date. Each team taking care of their own components and their integration points.

The DDD high level design concept map

These are the main concepts that we’ve explored so far, and how they relate to each other.

Key Takeaways from Practical Object-Oriented Design by Sandi Metz

2024-02-27T00:00:00+00:00

Practical Object-Oriented Design: An Agile Primer Using Ruby by Sandi Metz is one of those books that everybody who writes or aspires to write object-oriented code should read. Indeed, reading through this book will be valuable for seasoned practitioners and inexperienced novices alike. Whether it be to discover new concepts, remember why they are important, or articulate the reasons behind that warm fuzzy feeling you get in your stomach when you read well designed code, POODR can help.

I personally really like this book, and here at End Point it does have quite a following as well; it was the subject of a study group that we ran back in 2016. I like to dust it off every now and then to give it a re-read. To help with that, I’ve come up with a list of key takeaways from the book, with some of my own interpretations sprinkled in. For me, it serves as a sort of summary to help commit the book’s contents to memory. I thought I’d share it with you today.

While this book uses the Ruby language for its examples and discussions, the concepts it describes are equally applicable to any classical object-oriented language. Dynamically typed language users do get a little more mileage than users of statically typed ones. But still, something like 90% of the content is relevant to both. For this summary, I’ve taken care not to tie the discussion to Ruby too much and be as language agnostic as possible. I’ve chosen to write the code examples in C#.

Images taken from the book. Code taken from the book’s examples in Ruby and translated to C#.

Chapter 1: Object-Oriented Design

About design

Following the principles and patterns of object-oriented design produces code that is both cost-effective and a joy to work with. “Cost effective” means that it doesn’t take more effort than necessary to evolve, to change.
The reason design is important is because software changes. A good design is one that makes software easy to change.
Object-oriented design sees the world as a collection of parts that interact with each other. The parts we call “objects”, and the interactions we call “messages”.
In order to send messages to each other, objects need to have some knowledge about one another. This knowledge produces “dependencies” between them.
Managing these dependencies is a big part of object-oriented design. OOD aims to create dependencies in such a way that they don’t make the process of changing objects too difficult.
Design is important no matter the size of the application. Because both small and large applications change. And change is what design allows. A badly designed small application will eventually become a badly designed large one.
Design is the way in which code is arranged. Good design is an arrangement of code that makes change easy.
Our job as developers is to take our application’s requirements and our knowledge of design principles and use them to produce code that is cost effective today and tomorrow: code that is easy to change.
The idea is not to predict future changes. Instead, we have to accept that change will come and prepare for it. We prepare for it by writing code that leaves our options open for the future.
“The purpose of design is to allow you to design later, and its primary goal is to reduce the cost of change.”

Failures of design

Design fails when you don’t do it. Code bases that lack in design will eventually evolve into unmaintainable messes, where change becomes increasingly hard even for the most minor new requirements. “Throwing everything away and beginning from scratch” becomes a viable alternative.
Design fails when you overdesign. Armed with basic design skills, it’s easy to fall into the trap of developing wrong abstractions, applying principles incorrectly, seeing the wrong pattern in the wrong context. Applications that suffer from overdesign become gigantic castles of code full of indirection that become hard to change.
Design fails when you separate it from programming. Design is best executed as an iterative and incremental process with a quick feedback loop. The design needs to be adjusted frequently, as understanding of the domain changes. Design that is dictated to programmers from on high as part of a “Big Up Front Design” is doomed to failure. Such arrangements are not agile enough to be resilient to requirement changes.

Agile and design

Agile development says: “Avoid Big Up Front Design because you can’t know what the application will end up being because requirements always change and they do so often.”
Agile also says: “Good design is essential. Because change comes often, your code needs to be ready to accommodate those changes in an efficient and cost effective way.”
Design is not a “one time at the beginning of the project” type of task. It is an ongoing, iterative and incremental task that happens as requirements change, and as our domain knowledge and skills increase.

Metrics

Bad object-oriented design metrics are an indicator of a bad design. But good metrics are not an indicator of good design. A code base with bad metrics will most likely be hard to change.
The ideal software metric would be “cost per feature per time interval”. But this is nigh on impossible to calculate because “cost”, “feature”, and “time interval” are in most cases nebulous concepts.
Still, “cost per feature per time interval” tells us that our goal should always be to write code with a low cost per feature. Making sure that it is also low cost to evolve in the future.

Technical debt

Technical debt is borrowing time from the future. That is, putting out a bad design today in order to release a feature quickly. Tomorrow, when change comes, the bad design will prevent cost effective change. So time will have to be spent refactoring, turning the bad design into a good one. If refactoring doesn’t happen, the debt increases, making future changes more and more expensive.
How much design you do depends on your skill and your time frame. You can’t do so much design that it prevents you from delivering on time. Design is an investment, and for an investment to be good, it needs to return some profit. Good design’s returns are quick and plentiful.
“The trick to getting the most bang for your design buck is to acquire an understanding of the theories of design and to apply them appropriately, at the right time, and in the right amounts.”

Chapter 2: Designing Classes with a Single Responsibility

About classes

Classes are the most basic organizational structure of object-oriented systems written with class-based object-oriented languages. As such, that’s the first thing that we focus on when designing such systems.
Your first instinct should be to keep things simple. Use classes to model only the features that your application needs today and make sure that they are easy to change tomorrow.
“Design is more the art of preserving changeability than it is the act of achieving perfection.”

Write code that is TRUE

In order to be easy to change, code should be TRUE:
Code should be “Transparent”. It should be easy to tell what will be the consequences of changing the code.
Code should be “Reasonable”. The cost of a change should be proportional to the size of the requirement that provoked the change.
Code should be “Usable”. The code should be easy to reuse in situations other than the one it’s currently being used in.
Code should be “Exemplary”. The code should exhibit qualities that guide and/or encourage those who change it to keep and replicate those qualities.
The Single Responsibility Principle is a prerequisite to creating code that is TRUE.

Single Responsibility

A class should have one single responsibility. That means that it needs to do one thing and do it well. It needs to be as small as possible and fulfill a single purpose. It needs to have only one reason to change.
A good way to identify what classes your system needs is to read through your user stories or problem descriptions and identify nouns. Those nouns are good candidates for classes.
If there are verbs and properties associated with those nouns, then it is most likely a class. Because classes represent bundles of both data (attributes) and behavior (methods).
Classes that have many responsibilities are hard to reuse. And because they are not “Usable”, they are not easy to change.
A class that has many responsibilities usually has unrelated code tangled together within it. This makes the class hard to reason about, and hard to reuse.
In order to reuse the behavior defined within a class with multiple tangled responsibilities, you either need to duplicate code or use the entire class, even the parts that you don’t need.
If you use a class that has many reasons to change, when something unrelated to your use case changes, you will still have to change your code. This is unexpected and surprising. This is not “Transparent”.
Depending on classes that have many responsibilities increases the chances of your application breaking.
A good way to determine whether a class has a single responsibility is to try to enunciate what it does in a single sentence. That sentence should be simple, because classes should be simple. Look out for the words “and” and “or” in this sentence, as they point to it having more than one responsibility.
Another good way to determine whether a class has a single responsibility is thinking about every one of its methods as a question that the class would be able to respond to if it were a sentient being. For example: “Array, what is your length?” If the question doesn’t make sense, then maybe the method does not belong in the class.
Cohesion is the measure of how related to their core purpose the elements of a component are. Classes that have a single responsibility are highly cohesive because all of their parts work towards a single goal.

When to make design decisions

Only design as much as you need to for right now. Don’t make design decisions prematurely. Sometimes waiting for more information before committing to a design is the way to go. More information in the future will often reveal a better design.
Consider postponing design decisions when the information available to you today does not point clearly to a good design. Also, when the cost of not doing it now does not considerably make tomorrow’s change more expensive.
On the other hand, consider that a class that’s left in a “bad state” may be reused by others, making their code depend on badly designed code. The application will suffer as a result.
The structure of a class is supposed to reveal your design’s intention to other developers. When it doesn’t, when it is not “Exemplary”, then future maintenance costs increase.
The tension between “improve it now” and “improve it later” is always present. Our job as designers is to strike a good balance “between the needs of the present and the possibilities of the future” so that the costs of change are kept low.

Techniques for writing code that’s easy to change

Depend on behavior, not data: hide instance variables. Instead of accessing instance variables directly, use accessor methods. Even from within the class that owns them. “Always send messages to access data.”
That way you consolidate the knowledge of what the data represents in a single place. That’s the Single Responsibility Principle in action. Changing it becomes easy as a result because instead of changing references to a variable in potentially multiple places; you only need to change the definition of a method, in a single location.
Depend on behavior, not data: hide data structures. When code depends on or receives as input a complex data structure like a big array or hash, encapsulate the data structure in a class with a clear interface, instead of accessing and manipulating the structure directly.
Directly manipulating complex data structures is a style of coding that tends to propagate. If the incoming data structure changes, even slightly, then a lot of your code also needs to change because it depends on its very particular structure.
Handling complex raw data structures through classes and messages with clear, intention-revealing names demystifies the structure and gives it meaning within the context of the application domain.

For example, instead of this…

class ObscuringReferences
{
    int[][] data;

    public ObscuringReferences(int[][] data)
    {
        this.data = data;
    }

    public IEnumerable<int> GetDiameters()
    {
        return data.Select(cell => cell[0] + (cell[1] * 2));
    }
}

…do this:

class RevealingReferences
{
    IEnumerable<Wheel> Wheels { get; set; }

    public RevealingReferences(int[][] data)
    {
        Wheels = Wheelify(data);
    }

    // This method is now more readable.
    public IEnumerable<int> GetDiameters()
    {
        return Wheels.Select(wheel => wheel.Rim + (wheel.Tire * 2));
    }

    // Now everyone can send rim/tire to wheel.
    record Wheel(int Rim, int Tire);

    private IEnumerable<Wheel> Wheelify(int[][] data)
    {
        return data.Select(cell => new Wheel(cell[0], cell[1]));
    }
}

Enforce single responsibility everywhere: extract extra responsibilities from methods. Methods should also have a single responsibility. Just like classes, that makes them easy to reuse, change, and understand.
To determine if a method has a single responsibility, the same techniques that work for classes apply. Try to enunciate their purpose in a single sentence, and ask them what they do.
Methods that iterate on items and act upon them too are a common case of multiple responsibilities. Separating iteration and action into two methods is a common refactoring to correct it.
Complex calculations embedded within methods are also good candidates to be separated into other methods. It gives them a name and makes them reusable.

For example, instead of this:

IEnumerable<int> GetDiameters()
{
    return Wheels.Select(wheel => wheel.Rim + (wheel.Tire * 2));
}

…do this:

// First - iterate over the collection.
IEnumerable<int> _GetDiameters()
{
    return Wheels.Select(wheel => GetDiameter(wheel));
}

// Second - calculate diameter of ONE wheel.
int GetDiameter(Wheel wheel)
{
    return wheel.Rim + (wheel.Tire * 2);
}

These refactorings are useful and necessary even when you don’t know what the final design will look like. In fact, these refactorings (and good practices like these) will often reveal the final design.
Small methods with a single responsibility have many benefits. They make a class’s details, features, and components more obvious, they are self-documenting, encourage reuse, establish a style of programming that is self-perpetuating, become easy to move to another class when and if that time comes.
Enforce single responsibility everywhere: isolate extra responsibilities in classes. Move the responsibilities that are extraneous to a class into another class. If you can afford it, create a separate class to hold them. If not, at least encapsulate them in an embedded class so that they are contained and don’t leak.
Embedded classes say: This class only has meaning and value when thought about within the context of this other class.
Embedded classes can be easily promoted to independent classes later if the need arises.
Once all methods inside a class have a single responsibility and are each doing the smallest useful thing, it becomes easier to identify the features that may belong to another class.
The purpose of design is not to produce “perfect” code but instead to produce code that’s “good enough”.
The Single Responsibility Principle “allows change without consequence and reuse without duplication”.

Chapter 3: Managing Dependencies

About dependencies

Objects should have a single responsibility and do the smallest useful thing. This means that, in order to fulfill complex application requirements, objects need to collaborate with one another.
Objects collaborate by knowing things about and sending messages to each other. That creates dependencies. A good design manages these dependencies, making sure they don’t couple objects so much that change becomes painful.
Coupling measures how much interdependency exists between software components. High coupling makes things hard to change.
An object has a dependency when it knows the name of another class.
An object has a dependency when it knows the name of a method from another class.
An object has a dependency when it knows the arguments of that method.
An object has a dependency when it knows the order of those arguments.
Dependencies create a situation where if an object changes, then other objects that depend on it may be forced to change as well.
Dependencies couple objects to each other. Highly coupled objects behave as if they were a unit. It becomes hard to reuse one without the other. If not managed properly, dependencies will disseminate and entangle the entire code base.
Some dependencies are unavoidable. So the purpose of design is to reduce and contain dependencies. Ensure objects only have the minimum number of dependencies that they need to do their jobs. Keep the essential ones, remove the rest.

Techniques for writing loosely coupled code

Dependency injection. It can help eliminate dependencies on concrete classes. Instead of instantiating new objects of another class inside your object, let the object receive it as a constructor or method parameter. The object’s users can do the instantiation.
An object that knows less can often times do more. The knowledge of how to instantiate a particular object limits its potential. Object creation and utilization don’t need to be contained within the same unit of code.
When an object hard-codes the reference to a class, it advertises that it can’t work with any other type. Replace the reference to the concrete class with an abstraction (e.g. an interface or duck type). That gives it the flexibility to be able to collaborate with other objects that respond to the same messages.

With dependency injection you can turn this:

class Gear
{
    float Ratio { get; set; }
    int Rim { get; set; }
    int Tire { get; set; }

    public Gear(float ratio, int rim, int tire)
    {
        Ratio = ratio;
        Rim = rim;
        Tire = tire;
    }

    public float GetGearInches()
    {
        return Ratio * new Wheel(Rim, Tire).GetDiameter();
    }
}

Into this:

class Gear
{
    float Ratio { get; set; }
    Wheel Wheel { get; set; }

    // Instead of rim and tire, Gear's constructor now receives a wheel.
    public Gear(float ratio, Wheel wheel)
    {
        Ratio = ratio;
        Wheel = wheel;
    }

    public float GetGearInches()
    {
        // Instead of creating a new wheel, it uses the one that's been injected.
        return Ratio * Wheel.GetDiameter();
    }
}

Sometimes it is not possible to remove a dependency from an object. In those cases, your best bet is to isolate it.
Isolate dependencies: isolate instance creation. Sometimes it is not possible to apply dependency injection. In those cases, the next best thing is to encapsulate instantiation of external classes into their own methods.
An instantiation encapsulated in a method allows the code to clearly and explicitly communicate that there’s an extraneous dependency here. One that we’d like to remove but for now cannot. We also protect the class from that dependency propagating through it.
Isolate dependencies: isolate vulnerable external messages. The same technique can be applied to invocations of methods on external classes. Encapsulate such calls into their own methods in order to contain the dependency.

Here’s what isolating some dependencies could look like. From this…

float GetGearInches()
{
    return Ratio * new Wheel(Rim, Tire).GetDiameter();
}

…to this:

float GetGearInches()
{
    return Ratio * GetWheelDiameter();
}

// The dependency on the Wheel class is isolated in this method.
int GetWheelDiameter()
{
    return new Wheel(Rim, Tire).GetDiameter();
}

Reduce argument dependencies: use keyword arguments. If your language supports them, keyword arguments are a great way of reducing the dependency incurred via method invocations. They allow the parameters to be sent in any order, which means that changes to the method’s definition and signature are less likely to cause the callers to have to also change. Also, they have a self-documenting property on both caller and callee. (See named arguments in C# and keyword arguments in Ruby).
Reduce argument dependencies: explicitly define defaults. If your language has the feature, parameter defaults are a great way of reducing dependencies to method parameters, as establishing a default for a parameter makes it optional.
Reduce argument dependencies: isolate multiparameter initialization. If you don’t own the code for a complex object initialization or method invocation, you can always encapsulate it in an object or method of your own. It can be done with a thin wrapper that exposes an interface that follows the techniques we’ve discussed and that uses the language of your application.
Classes should depend on things that change less often than they do.
There are three truths about code related to change and dependencies:
1. “Some classes are more likely to change than others”.
2. “Concrete classes are more likely to change than abstract classes”.
3. “Changing a class that has many dependents will have many consequences”.
It’s OK to depend on classes with a low likelihood of change. For example, classes in the built-in library of your language generally will change less than your own custom classes. Framework classes commonly change less often too, but that may not always be the case if you framework is new or rapidly evolving.
Abstractions are generally much more stable than concretions. Because of this, it is safer to depend on abstract classes (e.g. interfaces and duck types) than on concrete ones.
Avoid classes that have lots of dependencies. Any changes done to them produce a ripple effect of changes throughout the code base. Also, because of that, people will go through great lengths to try to avoid changing them.
When thinking about dependents and likelihood of change, the following are harmless:
1. Classes with few dependents and low likelihood of change (e.g. specialized infrastructure interaction classes).
2. Classes with few dependents and high likelihood of change (e.g. concrete classes that implement your app’s domain logic).
3. Classes with many dependents and low likelihood of change (e.g. interfaces and other abstractions).
When thinking about dependents and likelihood of change, the following is harmful: Classes with many dependents and high likelihood of change (e.g. concrete classes that are used throughout the code base).

Chapter 4: Creating Flexible Interfaces

About interfaces

The messages that objects pass between each other are a big concern for design. In addition to what objects know (responsibilities), and who they know (dependencies), design cares about how they talk to one another. Messages pass between objects through their interfaces.
In a well designed application, the messages that pass between objects follow a pattern that’s closer to the diagram on the right than that of the diagram on the left:

Objects that expose too much of themselves and know too much about others are hard to reuse and make systems hard to change.
Objects that minimize what they expose of themselves and know little about others are easily reusable and changeable.
An object’s public interface is the set of messages that it responds to. That is, the set of methods that other objects are welcome to invoke. Good design calls for objects with clear and concise public interfaces.
Classes should have one responsibility, but they will likely have many methods. Some methods are more general and expose the main features of a class; they are the services that the class offers its callers. These should make up the class’s public interface. Other methods are more specific, serve to support those features, and contain implementation details internal to the class and uninteresting to callers. These make up the class’s private interface.
The methods in a class’s public interface:
1. “Reveal its primary responsibility”
2. “Are expected to be invoked by others”
3. “Are not likely to change”
4. “Are safe for others to depend on”
5. “Are directly covered by tests”
The methods in a class’s private interface:
1. “Handle implementation details”
2. “Are not expected to be invoked by other objects”
3. “Are likely to change”
4. “Are unsafe for others to depend on”
5. “May not even be referenced in the tests”
Public methods list the specific features of a class that allow it to fulfill its responsibility. They advertise to the world what the purpose of the class they belong to is.
Public methods are stable and are expected to not change often, so others are welcome to depend on them.
Private methods are not stable at all. They are hidden from others so nobody should depend on them.

Discovering less obvious objects and messages

When analyzing a problem domain, the nouns in the narrative usually become your first classes. These are called “domain objects”.
Don’t let domain objects be your only classes, though. Shift your focus toward messages and away from classes to discover new, less obvious objects that will implement key functionality. Not doing so will risk overloading your domain objects with more responsibility than what they can handle.
UML sequence diagrams are an excellent way to explore design alternatives. You can use them to draft objects and their interactions, i.e. the messages they send each other. They are quick, low cost, and allow easy communication of ideas between team members. Here’s an online tool that generates them based on plain text: sequencediagram.org.
The transition from class-based design to message-based design is one that yields more flexible applications. It means asking “I need to send this message, who should respond to it?” instead of “I know I need this class, what should it do?”.

Focusing on “what” instead of “how”

Public methods should focus on “what” instead of “how”. That is, they should express what the caller wants instead of how the callee must behave.
If you’re in a situation where an object calls many methods on another in succession, try to refactor so that all the logic is executed as a result of a single message. This consolidation reduces the size of the second object’s public interface, which reduces what callers need to know about it, which reduces dependency, which makes change easier. The caller only knows “what” it needs, not “how” to make the callee deliver.

When focusing on “what” instead of “how”, code like this:

class Trip
{
    IEnumerable<Bicycle> Bicycles { get; set; }
    Mechanic Mechanic { get; set; }

    public void Prepare()
    {
        foreach (var bike in Bicycles)
        {
            Mechanic.CleanBicyble(bike);
            Mechanic.PumpTires(bike);
            Mechanic.LubeChain(bike);
            Mechanic.CheckBrakes(bike);
        }
    }
}

class Mechanic
{
    public void CheckBrakes(Bicycle bike) { }
    public void CleanBicyble(Bicycle bike) { }
    public void LubeChain(Bicycle bike) { }
    public void PumpTires(Bicycle bike) { }
}

Can be transformed into code like this:

class Trip
{
    IEnumerable<Bicycle> Bicycles { get; set; }
    Mechanic Mechanic { get; set; }

    // This method was greatly simplified and its dependencies were reduced.
    public void Prepare()
    {
        foreach (var bike in Bicycles)
        {
            Mechanic.PrepareBicycle(bike);
        }
    }
}

class Mechanic
{
    public void PrepareBicycle(Bicycle bike)
    {
        CleanBicyble(bike);
        PumpTires(bike);
        LubeChain(bike);
        CheckBrakes(bike);
    }

    // Notice how Mechanic's public interface was reduced considerably.
    // All of these methods are private now.
    private void CheckBrakes(Bicycle bike) { }
    private void CleanBicyble(Bicycle bike) { }
    private void LubeChain(Bicycle bike) { }
    private void PumpTires(Bicycle bike) { }
}

Liberate objects from their context

An object’s context is made up of the things that an object knows about others. What other objects it calls and how. What it needs in order to be able to work.
A good design tries to allow objects to work with minimal context. “Objects that have a simple context are easy to use and easy to test; they expect few things from their surroundings. Objects that have a complicated context are hard to use and hard to test; they require complicated setup before they can do anything”.
In order to reduce context, we need to reduce the knowledge that callers have about the other components they call. A simple public interface helps with that. In practical terms that means fewer and less verbose methods, fewer parameters, fewer dependencies.
Objects need to trust their collaborators to do their part. Focusing on what the caller wants instead of what the callee does is a way of keeping context in check. This allows objects to collaborate with others regardless of what type they are and what they do.
Dependency injection is a mechanism through which objects can collaborate with others when they don’t know their type. A dependency injected via parameter (declared as an interface or duck type) hides its identity from its user.
Naming the methods of this injected dependency from the perspective of the caller reveals a generic interface that offers the features that the caller wants in the vocabulary that it understands. The caller does not need to know what the injected dependency does, only what it needs it to do.
Highly coupled objects with verbose public interfaces say to their collaborators: “I know what I want, and I know how you do it”.
More decoupled objects with concise public interfaces say to their collaborators: “I know what I want, and I know what you do”.
Highly decoupled objects with concise public interface and minimal required context say to their collaborators: “I know what I want, and I trust you to do your part”.

When objects trust their collaborators, and focus on what they want instead of what others do, the previous Trip/Mechanic example can become like this:

class Trip
{
    public IEnumerable<Bicycle> Bicycles { get; set; }
    Mechanic Mechanic { get; set; }

    public void Prepare()
    {
        // Trip now fully trusts Mechanic, and doesn't even know what it does.
        Mechanic.PrepareTrip(this);
    }
}

class Mechanic
{
    // The knowledge of "how a mechanic prepares a trip" now completely lives
    // within Mechanic.
    public void PrepareTrip(Trip trip)
    {
        foreach (var bike in trip.Bicycles)
        {
            PrepareBicycle(bike);
        }
    }

    private void PrepareBicycle(Bicycle bike)
    {
        CleanBicyble(bike);
        PumpTires(bike);
        LubeChain(bike);
        CheckBrakes(bike);
    }

    private void CheckBrakes(Bicycle bike) { }
    private void CleanBicyble(Bicycle bike) { }
    private void LubeChain(Bicycle bike) { }
    private void PumpTires(Bicycle bike) { }
}

Rules of thumb for writing code with good interfaces

Create explicit interfaces. Be intentional and obvious when defining public and private methods. Use your language access modifiers (i.e. public, private, protected, etc). Your public methods should:
1. Be explicitly identified as such
2. Be more about what than how
3. Have names that are unlikely to change
4. Use keyword arguments
Respect the public interface of others. Invoke only public methods on the classes that you use. Avoid circumventing their public interfaces and directly calling private members. Depending on the private interface of framework and library classes is like a ticking time bomb. The reason they are private is because they are expected to change or disappear entirely.
Minimize context. Focus on “what” instead of “how” when designing public interfaces. Favor public methods that allow callers to access your classes’ functionality without having to know how they do it. Use interface and duck types to name methods from the perspective of and with the vocabulary of the callers.
If you have to interact with a class that does not have a clean interface, and you don’t own it or otherwise can’t refactor it so that it does, isolate it. Use the same techniques for dependency isolation mentioned in Chapter 3. Wrap the invocation in a new class or method to contain it and give that wrapper a clean public interface.
Follow the law of Demeter. The law of Demeter states that you shouldn’t chain multiple method calls that navigate across many different types of objects. In other words “talk only to your close neighbors” or “use only one dot”.

Violations ot the law of Demeter look like this:
customer.GetBicycle().Wheel.Rotate();

Violations of the law of Demeter make for code that’s not TRUE. Changes in the object at the end of the chain ripple through the entire chain. This is unexpected and laborious, making the code neither Transparent nor Reasonable. The class that uses the chain depends on all the objects in the chain, making it non-Usable. These chains are easy to replicate and harm changeability, making the code not Exemplary.
Always evaluate the cost of violating the law of Demeter versus the cost of abiding by it. Method chains that ultimately read an attribute are generally less harmful. Also, method chains on really stable classes like those of your language library or framework have low impact.
Delegation can appear to be a solution to law of Demeter violations. Unfortunately, all it does is remove the evidence that it’s there.
In reality, a violation to the law of Demeter indicates that there’s an object missing or that the public interface of an object is lacking. Find the object, and its interface, by thinking more about messages and less about classes. Define the interface by thinking about what the object needs of its collaborators, and not about how it can get it by itself.

Chapter 5: Reducing Costs with Duck Typing

About duck types

Duck types are public interfaces that manifest themselves across classes. When multiple classes accept the same messages (i.e. define methods with the same signature), they are said to be of the same duck type.
“Duck type” is a dynamic language concept. Static languages offer equivalent features via “interfaces”.
The difference is that, in statically typed languages, interfaces need to be explicitly defined in code and concrete classes need to explicitly implement them. On the other hand, duck types in dynamically typed languages need only be acknowledged in an abstract sense. They don’t have to be explicitly defined in code.
Duck types and interfaces establish a contract. A set of messages that a given object is expected to be able to receive. A protocol that users of these objects can be confident that they will adhere to.
Just as a class can implement multiple interfaces, an object can be of many duck types. That’s because interfaces and duck types materialize depending on the situation in which objects that implement them are used. The same object can be used in different places for different things. Each user will see the object from their own perspective, and each can expect it conform to a different interface. See the interface segregation principle.
Moreover, code that depends on an interface or duck type is flexible enough to collaborate with any concrete class that implements that interface or duck type. See the Liskov substitution principle.
As we’ve established, it’s better to depend on abstractions than to depend on concretions. So, users of an object should not care what its type is, only what it does. Behavior over identity. In other words, they should focus on messages and public interfaces, instead of specific classes. Duck types and interfaces bring to the forefront what an object does and abstracts away what it is.
Applying duck types to a situation makes the code more abstract and less concrete. Concrete code is easier to understand but harder to extend. Abstract code is harder to understand at the beginning but easier to change. In the long run, abstract code tends to reduce maintenance costs.
When an object invokes methods on multiple objects in order to achieve a single purpose, that’s a situation where a duck type may be helpful. Think from the perspective of the caller and what it needs to come up with a message that makes sense for it to send its many collaborators. That method should be part of the public interface of each of its collaborators. To the caller’s eyes, each of its collaborators belong in the same duck type.

Writing code that leverages duck types

Whenever you see conditional logic that sends a different message depending on the concrete class of a given object, that’s the code telling you that it needs a duck type or interface.
Come up with a message that makes sense from the perspective of the caller and add it to each of the classes expected by your code in the conditional. These classes now share the same public interface, they are of the same duck type. Then remove the conditional and just call that method. Replace conditional logic with polymorphism.
In general, try to avoid code that explicitly mentions concrete classes or checks for the existence of particular methods in order to determine further behavior. Instead, come up with a shared interface and send those messages to the collaborators regardless of their actual type.

Higly conditional and concrete logic like this…

class Trip
{
    public IEnumerable<Bicycle> Bicycles { get; set; }
    public IEnumerable<Customer> Customers { get; set; }
    public Vehicle Vehicle { get; set; }

    public void Prepare(IEnumerable preparers)
    {
        foreach (var preparer in preparers)
        {
            if (preparer is Mechanic)
            {
                ((Mechanic)preparer).PrepareBicycles(Bicycles);
            }
            else if (preparer is TripCoordinator)
            {
                ((TripCoordinator)preparer).BuyFood(Customers);
            }
            else if (preparer is Driver)
            {
                ((Driver)preparer).GasUp(Vehicle);
                ((Driver)preparer).FillWaterTank(Vehicle);
            }
        }
    }
}

class Mechanic
{
    public void PrepareBicycles(IEnumerable<Bicycle> bicycles) { }
}

class TripCoordinator
{
    public void BuyFood(IEnumerable<Customer> customers) { }
}

class Driver
{
    public void FillWaterTank(Vehicle vehicle) { }
    public void GasUp(Vehicle vehicle) { }
}

…can be rewritten to be more abstract if we leverage polymorphism. Like this:

class Trip
{
    public IEnumerable<Bicycle> Bicycles { get; set; }
    public IEnumerable<Customer> Customers { get; set; }
    public Vehicle Vehicle { get; set; }

    // This method can be much simpler now, and abstract.
    // Ready to collaborate with any "TripPreparer".
    // The conditional logic has been replaced with polymorphism.
    public void Prepare(IEnumerable<ITripPreparer> preparers)
    {
        foreach (var preparer in preparers)
        {
            preparer.PrepareTrip(this);
        }
    }
}

// New interface that all preparers implement. It has a single method.
// It greatly simplifies the communication between Trip and its many
// possible preparers.
interface ITripPreparer
{
    void PrepareTrip(Trip trip);
}

class Mechanic : ITripPreparer
{
    public void PrepareTrip(Trip trip)
    {
        PrepareBicycles(trip.Bicycles);
    }

    private void PrepareBicycles(IEnumerable<Bicycle> bicycles) { }
}

class TripCoordinator : ITripPreparer
{
    public void PrepareTrip(Trip trip)
    {
        BuyFood(trip.Customers);
    }

    private void BuyFood(IEnumerable<Customer> customers) { }
}

class Driver : ITripPreparer
{
    public void PrepareTrip(Trip trip)
    {
        FillWaterTank(trip.Vehicle);
        GasUp(trip.Vehicle);
    }

    private void FillWaterTank(Vehicle vehicle) { }
    private void GasUp(Vehicle vehicle) { }
}

The one exception to this rule is when dealing with exceptionally stable classes. Like those in your language libraries, where the introduction of duck types would mean modifying core language libraries. Explicit type checks against these classes are usually low cost.
Duck types are abstract and less obvious in the code. That’s why they need to be well documented and tested.

Chapter 6: Acquiring Behavior through Inheritance

About inheritance

Inheritance establishes a relationship between two classes where it is said that a subclass B “is a” superclass A. Subclass and superclass are also referred to as derived class and base class, respectively.
Inheritance can be more technically defined as an “automatic message forwarding mechanism”. That is, when a subclass receives a message that it cannot respond to directly (i.e. a method that it does not implement), the language runtime takes care of automatically sending the message to the superclass.
That is, inheritance establishes a hierarchy where superclasses share their code with their subclasses.
Subclasses are meant to be specialized versions of their superclass. Subclasses should be “the same, plus more” when compared to their superclass. They should offer the same public interface.
Inheritance is ideal to solve the problem where you need a series of slightly different classes that share a lot of behavior.
A telltale sign that inheritance needs to be applied is when code contains an “if” statement checking an attribute that contains the “category” of the object, and based on that determines what code to execute. Watch out for this anti-pattern and for variables with names like “type”, “category”, “style” that control branches in behavior.
This is an anti-pattern that reveals that the object knows too much and needs to be broken down into smaller pieces. It increases the costs of change.

Here’s what the anti-pattern looks like:

class Bicycle
{
    string Style { get; set; }
    string TapeColor { get; set; }
    string FrontShock { get; set; }

    public Bicycle(Dictionary<string, string> options)
    {
        Style = options["style"];
        TapeColor  = options["tape_color"];
        FrontShock = options["front_shock"];
    }

    // Checking 'style' starts down a slippery slope.
    public Dictionary<string, string> GetSpares()
    {
        if (Style == "road")
        {
            return new() {
                ["chain"] = "11-speed",
                ["tire_size"] = "23",
                ["tape_color"] = TapeColor
            };
        }
        else if (Style == "mountain")
        {
            return new() {
                ["chain"] = "11-speed",
                ["tire_size"] = "2.1",
                ["front_shock"] = FrontShock
            };
        }
    }
}

Applying inheritance

Be on the lookout for existing classes that may lead you down the wrong path when it comes to inheritance. More often than not, classes that already exist in the code base are not good candidates for extension via inheritance. They are not good candidates to be superclasses.
The path forward is likely to be a new class to serve as the base, and then update your existing class to be a subclass. Then add other subclasses as peers of it.
For inheritance to work, the objects being modeled need to truly share a generalization-specialization relationship.
The superclass needs to define the common behavior that is shared among subclasses. The subclasses define the specializations.
In many cases, the superclass should be abstract, meaning that they are not supposed to be instantiated. They represent an incomplete object which only becomes whole when looked at in the context of each of its subclasses.
It almost never makes sense to create a superclass with only a single subclass. In fact, creating an inheritance hierarchy with two subclasses is often risky. You risk coming up with the wrong abstraction.
Three subclasses is the sweet spot to commit to inheritance. Put off the decision to implement inheritance until that point, if you can. That’s the point when there’s enough information available to confidently determine an abstraction that will be useful and cost effective.
If you put off implementing an inheritance hierarchy, then you won’t be able to share code between the highly related classes. That will likely lead to code repetition, which is also costly. Consider what costs more: having the repetition for the time being; or doing nothing and waiting for more information to avoid making the wrong decision.
“Every decision you make includes two costs: one to implement it and another to change it when you discover that you were wrong”.
When refactoring towards an inheritance hierarchy, consider that “promoting” code from the concrete subclass up into the abstract superclass is often easier and less error prone.
Errors in promoting are easy to identify and fix. All that can happen if you miss a promotion is that a subclass that was meant to inherit some behavior won’t have it.
Going in the opposite direction and missing a “demotion” will produce design errors that are harder to spot and have dire consequences if left alone.
That would mean that concrete behavior, which does not apply to all subclasses, stays incorrectly in the abstract base class. That’ll throw a wrench in the works and the whole inheritance hierarchy will be on shaky grounds. The abstract base class won’t be generic enough and subclasses will be tempted to circumvent it.
“The general rule for refactoring into a new inheritance hierarchy is to arrange code so that you can promote abstractions rather than demote concretions”.
The template method pattern provides a clean way of defining a common basic algorithm in the superclass and allowing subclasses to supply specializations for it. Superclasses can define an algorithm, and call certain methods in key points within it. These are extension points. These methods can then be implemented by subclasses, letting them control part of the overall logic.
When promoting concrete code to the more abstract superclass, consider using the template method when methods cannot be promoted wholesale, and have to be broken up instead. The parts that can be promoted become the template method; the parts that can’t be become the specialization methods that each concrete subclass implements.
To avoid future bugs, superclasses should provide default implementations for the specialization methods that it expects its subclasses to implement. These can be no-ops or, even better, raise errors. These errors let developers know that extending this inheritance hierarchy requires these methods to be implemented.
Hook methods are a slightly lighter iteration of the template method concept that helps alleviate superclass-subclass coupling. Same principle: let the superclass send a message that the subclass implements in order to provide a specialization.
A hook method need not be a part of a common abstract algorithm, hence the slight distinction from the full fledged template method design pattern.
Beware of subclasses explicitly invoking functionality on their superclasses. Languages often offer keywords such as “base” or “super” that allow easily sending messages to superclasses. These are dangerous because they couple subclasses with their superclasses. They reveal that subclasses know the general algorithm.
The template method pattern and hook methods invert this dependency, allowing the superclass to call the subclass. Allowing the subclass to provide specializations without knowing too much about the superclass.

Here’s an example of a properly factored inheritance hierarchy:

// The main purpose of the base class is to establish a basic functionality
// that can be easily extended by subclasses.
// This class cannot be instantiated, as given by the "abstract" modifier.
// This means that our application has no need of holding onto pure Bicycle
// instances, only the concrete subclasses are to be used.
// This abstract class is just a vehicle for sharing code between other classes.
abstract class Bicycle
{
    public string Size { get; set; }
    public string Chain { get; set; }
    public string TireSize { get; set; }

    // Notice how this constructor implements the template method pattern
    // in order to allow subclasses to make changes to the overall algorithm.
    // Specifically, it allows them to provide default values for the Chain and
    // TireSize attributes as well as run any additional logic after
    // initialization.
    public Bicycle(Dictionary<string, string> options)
    {
        Size = options.GetValueOrDefault("size");
        Chain  = options.GetValueOrDefault("chain") ?? GetDefaultChain();
        TireSize = options.GetValueOrDefault("tire_size") ?? GetDefaultTireSize();

        AfterInitialize(options);
    }

    // This method establishes the basic spares information and allows
    // subclasses to supply more by calling the GetLocalSpares hook method.
    public Dictionary<string, string> GetSpares()
    {
        var defaultSpares = new Dictionary<string, string> {
            ["tire_size"] = "23",
            ["chain"] = "11-speed"
        };

        return new(defaultSpares.Concat(GetLocalSpares()));
    }

    // This method, which is marked as abstract, has to be implemented by
    // subclasses. It allows subclasses to contribute specializations.
    protected abstract string GetDefaultTireSize();

    // These methods, marked as virtual, all have default implementations of
    // varying complexity but the important aspect is that they can be
    // overridden by subclasses. They also allow subclasses to contribute
    // specializations.
    protected virtual void AfterInitialize(Dictionary<string, string> options) { }
    protected virtual Dictionary<string, string> GetLocalSpares() => new();
    protected virtual string GetDefaultChain() => "11-speed";
}

// Notice how the following concrete subclasses are very simple.
// Extending this kind of code is easy, because creating new subclasses is easy.
// They leverage their abstract base class to implement most of their features.
// Their job is to supply specializations on the core logic defined in the base
// class. To do so, they override the hook methods defined by the base class.
class RoadBike : Bicycle
{
    public string TapeColor { get; set; }

    public RoadBike(Dictionary<string, string> options) : base(options) { }

    protected override void AfterInitialize(Dictionary<string, string> options) =>
        TapeColor = options.GetValueOrDefault("tape_color");

    protected override Dictionary<string, string> GetLocalSpares() =>
        new() { ["tape_color"] = TapeColor };

    protected override string GetDefaultTireSize() => "23";
}

class MountainBike : Bicycle
{
    public string FrontShock { get; set; }
    public string RearShock { get; set; }

    public MountainBike(Dictionary<string, string> options) : base(options) { }

    protected override void AfterInitialize(Dictionary<string, string> options)
    {
        FrontShock = options.GetValueOrDefault("front_shock");
        RearShock = options.GetValueOrDefault("rear_shock");
    }

    protected override Dictionary<string, string> GetLocalSpares() =>
        new() { ["front_shock"] = FrontShock };

    protected override string GetDefaultTireSize() => "2.1";
}

class RecumbentBike : Bicycle
{
    public string Flag { get; set; }

    public RecumbentBike(Dictionary<string, string> options) : base(options) { }

    protected override void AfterInitialize(Dictionary<string, string> options) =>
        Flag = options.GetValueOrDefault("flag");

    protected override Dictionary<string, string> GetLocalSpares() =>
        new() { ["flag"] = Flag };

    protected override string GetDefaultChain() => "10-speed";
    protected override string GetDefaultTireSize() => "28";
}

About roles

Using classical inheritance is always optional. Every situation that calls for inheritance could be solved using another technique that allows for sharing code between otherwise unrelated classes.
The concept of “roles” is an alternative to classical inheritance. This concept emerges from the need of multiple classes to be used in a particular context to do the same thing. So they themselves need to share behavior.
Think of a role as an augmented form of a duck type. A group of classes are said to play the same role when they belong in the same duck type or implement the same interface. In addition to exposing the same public interface, roles allow them to share internal behavior.
Roles are ideal for storing responsibilities that are orthogonal to classes. It allows classes that are otherwise unrelated to share behavior. They establish a “behaves like” type of relationship between objects, as opposed to the “is a” relationship that is established with inheritance.
When you include a module into an existing class, all the methods defined in the module become available to the class. This is the same thing that happens when a subclass inherits from a superclass.
Many languages offer native features to allow for this kind of relationship between objects. In Ruby, we use Modules. Other languages use Mixins, Traits, Default Methods. Simply put, all these are ways of bundling together a group of methods that can be easily plugged into existing classes.

Writing inheritable code

The same principles, techniques, and anti patterns that apply to the design of duck types and inheritance hierarchies also apply to roles.
Beware of objects that use a variable with a name like “type”, “category” or “kind” to determine what code to execute. The object is likely concealing (and acting like) two or more types. These would be subclasses or module includers.
When code is checking the type of an object to decide which message to send it, that’s a signal that there’s a missing abstraction. There’s a duck type or role in there that needs to be explicitly brought to light. A public interface needs to be defined for it. If there is a need to share behavior, put it in a module, mixin, etc.
“All of the code in the abstract superclass should apply to every class that inherits it”.
Beware of subclasses or module includers that override a superclass/module method just to raise a “not implemented” error. Chances are that if only part of the superclass applies to it, then it doesn’t belong in the hierarchy. Or maybe the whole hierarchy needs a redesign.
Subclasses agree to the contract specified by their superclasses. They must respond to every message in the superclass’s public interface, accept the same types of inputs and return the same types outputs.
Put in other words, “subtypes must be substitutable for their supertype”. That is, all subclasses should act like their superclass. This means that any code that expects a superclass should be able to work, without change, with all its subclasses as well. That’s the Liskov substitution principle.
Through the concept of variance, subclasses have a slightly higher degree of freedom. Subclasses can accept inputs of more abstract types and can return outputs of more concrete types than those specified in the superclass’s public interface while still being substitutable for their superclass.
For example, given a class “Object” that is a superclass of a class “String”; if a method in a superclass “MyClass” accepts a String parameter, a subclass of MyClass could override that same method and accept Object and still be compliant. Likewise, if a method in a superclass returns an Object result, the subclass could return a String for that same method, and still be compliant. Still be substitutable.
In other words, some code that sends a message with a String parameter can send the same message to a receiver that accepts Object. Likewise, some code that expects an Object as a result of sending a message can send the same message to a receiver that returns a String. Because a String “is an” Object, any code that works with an Object can work with a String, it’ll just treat it like an Object and only access Object’s public interface, which String fully supports.

This is what variance allows:
class Superclass
{
    public virtual Object DoSomething(String parameter) => new Object();
}

class Subclass : Superclass
{
    public override String DoSomething(Object parameter) => "the result";
}
Be aware that C# currently does not support variance in parameters, only in return types. So this code would not actually work as it is, since the parameter types are different.

The template method pattern is the ideal technique for creating superclasses that are easy to inherit from. It allows clean separation of an abstract algorithm from the concrete specializations.
Be on the lookout for code that directly invokes superclass behavior with keywords like “super” or “base” etc. Instead, use hook methods to allow subclasses to contribute to parts of the common algorithm.
Favor shallow hierarchies instead of deep ones. Narrow is also preferable to wide. Wide ones are easier to live with as long as they are shallow. But deep and wide ones are a maintenance nightmare. That is, keep the vertical levels of inheritance as low as you can. Hierarchies with many layers of superclasses are hard to understand and maintain.

Chapter 8: Combining Objects with Composition

About composition

Composition establishes a “has a” relationship between objects. It is a technique where you combine simple, independent objects to turn them into larger, more complex ones. Composition combines distinct parts so that the resulting entity is more than the sum of its parts.
In composition, the container object (or composed object) “has a” contained component (or part). Mechanically, this usually means that the container’s class has an attribute which holds a reference to the part object. It’s a dependency that’s usually injected via constructor parameter.
The container communicates with the part via its public interface. The part plays a role, and the container collaborates with it. This means that containers generally interact with their parts through interfaces or duck types.
Composition is generally a cheaper alternative to code sharing when compared to inheritance.
When refactoring from inheritance into composition, the parts sometimes need to share some code, in addition to sharing the same public interface. This is because all possible parts play the same role for the container. In these cases, an inheritance hierarchy of parts may be what’s needed. Or, they could share behavior via modules or mixins.
In technical terms, the technique of composition takes two forms: aggregation and, well, composition. Under composition, parts don’t have any use or value outside of their container objects. Under aggregation, on the other hand, parts can live on their own.

Factories

When creating certain objects becomes complex, encapsulate that complexity into a factory. That way the knowledge is stored in a single place in the code base. In principle, factories are simple: They are objects that create other objects.
An advantage of factories is that they make the process of turning complex data structures into objects easy. You can have a “specification”, stored as pure data in a file or database. The factory can then implement the logic that understands the meaning of the data structure and how to create living objects based on it.

Deciding between inheritance and composition

Inheritance and composition are fundamentally code arrangement techniques where logic is distributed among various objects. With inheritance, objects are organized into a strict hierarchical structure and get automatic message delegation. With composition, objects are independent from each other but messages need to be manually delegated.
In general, “favor composition over inheritance”. Composition is lower cost (i.e. fewer dependencies) than inheritance in most circumstances where both could be used to solve a problem.

Pros and cons of inheritance

When properly applied, inheritance is excellent at producing code that is Reasonable, Usable and Exemplary.
Inheritable code is Reasonable because small changes in code can produce great changes in behavior. This is because code near the top of the hierarchy is defined once but used by all subclasses. Changing such code allows to alter the behavior of many subclasses.
Inheritable code is Usable because superclasses are literally designed to be easy to reuse. Inheritance hierarchies adhere to the open-closed principle. It’s easy to extend the hierarchy by creating new subclasses without having to touch existing code, thus, reusing it.
Inheritable code is Exemplary because it intrinsically provides a clear path to extend it. Even novice programmers won’t have a hard time creating new subclasses when the superclasses implement template methods and hooks which guide any extension efforts.
One important disadvantage of inheritance is that the cost of mistakes is considerably high. Incorrect applications of inheritance are costly, whether it be that the wrong abstraction was created or that inheritance was just the wrong tool for the job altogether.
Another disadvantage is that, for other contexts outside of the hierarchy, the ways in which it’s possible to interact with the hierarchy are limited. If the behavior defined within the hierarchy needs to be used, a subclass needs to be created. Other use cases may be incapable of tolerating that dependency.
If you’re writing a framework or a library, this aspect becomes even more important. You can’t know all the scenarios in which your library will be used, and forcing users to create subclasses in order to reuse the logic defined in the hierarchy may be more than what they can afford.

Pros and cons of composition

“When using composition, the natural tendency is to create many small objects that contain straightforward responsibilities that are accessible through clearly defined interfaces”. “Composition results in applications built of simple, pluggable objects that are easy to extend and have a high tolerance for change”.
When properly applied, composition is excellent at producing code that is Transparent, Reasonable and Usable.
Composable code is Transparent because small objects are easy to understand and changes have obvious effects. These objects also don’t necessarily form part of hierarchies, which means they are not susceptible to changes in superclasses.
Composable code is Reasonable because its behavior is easy to extend by just implementing new objects that play the role of parts. All new parts need to do is implement the public interface that the container object already expects.
Composable code is Usable because it’s made up of small independent objects. They don’t have any structural dependencies preventing them from being reused in different contexts, completely unrelated to the container or even the part role.
One disadvantage of composition is the fact that it may be more difficult to understand how the whole application works. While the individual objects may be small and simple, how they come together to solve problems may not be.
Another disadvantage is that objects need to delegate messages to each other manually, as opposed to inheritance where this happens automatically. This means that there is the explicit dependency of the container object having to know which messages to call on its parts.
Composition excels at separating containers from parts and assembling such objects. However, it doesn’t have an answer for the scenario where it is necessary to handle a collection of types of parts that are very similar to each other. That’s where inheritance comes in.
Use inheritance for “is a” relationships. Use duck types, interfaces, and behavior sharing via modules or mixins for “behaves like a” relationships. Use composition for “has a” relationships.

Chapter 9: Designing Cost-Effective Tests

The benefits of testing

The goal of design is to write code that is easy to change. In order to do that, we need good object-oriented design skills, good refactoring skills and good testing skills.
Good object-oriented design skills are needed because badly designed code, by definition, is hard to change.
Good refactoring skills are needed because design needs to be evolving constantly. As new requirements and new information about the domain become available, the code needs to adapt.
Good testing skills are needed because high value, solid tests enable continuous refactoring without fear of breaking the code.
Just like design, the true purpose of testing is to reduce costs. Tests do help reduce bugs, provide documentation, and improve the design; but those are only the means through which tests achieve their ultimate goal of reducing the cost of change.
Tests help by finding bugs: Test help expose bugs early in the process. Bugs are easier to find and cheaper to correct the closer in time we are to their introduction. Testing at the same time a feature is being implemented catches bugs before they go out the door. Bugs caught early are not given the chance to cause problems or have code depend on them.
Tests help by supplying documentation: Tests represent the best and most reliable documentation of the design. When static documents and memories get outdated and/or disappear, tests remain. Write tests that tell the story of how the code works.
Tests help by deferring design decisions: As a code base evolves, there will be spots in the code that are less than stellar. Spots which we’re not confident enough in to commit to a particular design. So we postpone making a decision and hack together a solution that works today. However, we know that it will need to be refactored to handle the requirements of tomorrow. These spots represent a lack of knowledge. Knowledge that the design is waiting for in order to improve. While waiting for that knowledge to come, we put the hack behind a clear, stable public interface and write our tests against that. In doing so, we’ll be free to refactor into a good design when the missing information arrives. Knowing that the tests have our backs.
Tests help by supporting abstractions: “Good design naturally progresses toward small independent objects that rely on abstractions”. One disadvantage to this is that, while small independent objects are easy to understand by themselves, the behavior of the whole application, with all the little objects working together, becomes obscured. Tests solve that problem by highlighting the abstractions, their interfaces, how to work with them, and how they work together.
Tests help by exposing design flaws: If tests are hard to write, that’s the perfect indicator that the code under test is hard to reuse. Which indicates high coupling, which indicates increased costs of change. If testing an object requires a lot of setup and a lot of other objects, then it requires too much context and has too many dependencies.

What, when and how to test

“One simple way to get better value from tests is to write fewer of them. The safest way to accomplish this is to test everything just once and in the proper place”.
Tests should focus only on the incoming messages that are defined in each object’s public interface (“A” in the picture above). That is, the public methods. Public interfaces expose the services that a class offers its users. They are also stable, so depending on them is safe. Tests that cover public methods are resilient to refactorings and add value because they exercise objects in the same way that their users in application code do.
Never test private methods (“B” in the picture above). They are meant to be used by the object internally. They change often and other objects should not depend on them because they will have to change with them. The same applies to tests. Tests that exercise private code break on every refactoring.
An object’s test suite should never assert the return value of outgoing messages that it sends to other objects (“C” in the picture above). These messages are part of the public interface of the receiver object, so the receiver’s test suite should be the one testing it.
On the other hand, an object’s test suite should always assert that necessary outgoing messages are sent, and with the correct parameters (“C” in the picture above).
A “test of state” is a test that asserts the return value of a method.
A “test of behavior” is a test that asserts whether the object under test calls a particular method on another object, how many times, and with what parameters.
A “query” is a method call with no side effects that is only made to get some value back.
A “command” is a method call that has side effects that are important to the overall application.
All public methods should be covered by tests of state. A test suite should only cover the public methods of its own object under test.
Queries should not be tested for state or behavior.
Commands should be tested for behavior.
Write tests first when it makes sense to do so. Writing tests before implementing the feature establishes an intention for the design from the beginning. Since tests are reused, they make sure the code to be written will have the bare minimum of reusability.
Testing first is no silver bullet, though. Even though it helps steer the design in the right direction, by itself it won’t produce a well-designed application. Fundamental object-oriented design techniques still need to be applied.
Well-designed applications are easy to change. Well-designed tests may never have to change. This is because they depend on abstractions and public interfaces, which are stable.
Two major styles of testing exist: Behavior Driven Development and Test Driven Development.
“BDD takes an outside-in approach, creating objects at the boundary of an application and working its way inward, mocking as necessary to supply as-yet-unwritten objects”.
“TDD takes an inside-out approach, usually starting with tests of domain objects and then reusing these newly created domain objects in the tests of adjacent layers of code”.
Both styles can be followed to produce valuable tests.

Writing valuable tests

Incoming messages (i.e. public methods) need to be covered by tests of state. That is, the values that they return must be validated.
Be on the lookout for public methods that don’t receive any calls. These are good candidates for deletion. If no other object calls it, then it needs to be private.
Objects should be tested in isolation. When that’s not possible, there’s a problem with the design. It means that the object is too coupled to its collaborators and can’t be reused on its own. It needs to be refactored.
It’s important that objects are tested in isolation because a test suite should care only about the one object that its testing. The other objects will be tested by their own test suites. Changes in an object should affect its own test suite, not that of other objects.
When the object under test depends on another object in order to work properly, refactor into dependency injection and have the test provide the dependency that way.
When using dependency injection, don’t pass in a concrete, “real” object in your tests. Instead, inject a test double or mock into the object under test.
Dependency injection also hints at the emergence of a role, interface, or duck type. Instead of depending on a concrete class, refactor the object under test to depend on a role. The double or mock in the test suite will be one of the objects that play the collaborator role that the object under test expects.
Private methods and query method calls need not be tested at all.
Testing private methods is redundant because they are internal to the object under test and invoked by public methods, which already have tests.
Private methods are also unstable. Not meant to be depended on because they change often. That will make for brittle tests.
Private methods covered by tests may mislead others in thinking that the method is stable and, thus, dependable.
Query method call results are not relevant to the overall application, only to the object under test. They are hidden within it. Also, the receiver of the query already includes tests for it, given that it is part of its public interface. So, they should be ignored by the test suite.
Command method calls do need to be covered by tests in order to prove that they were called with the correct parameters. In other words, it is the responsibility of the object under test to send that message, so its test suite needs to prove it.
Mocks are the way to test that command messages get sent. They help with tests of behavior. Using mocks injected into the object under test, a test case can validate that the method is called properly.
Commands should be tested for behavior, not state. So, mocks should not be used for tests of state. That is, tests should not be concerned with asserting what they return. However, they can be configured to return some value, if the operation requires it.
In dynamically typed languages that don’t have a compiler to do type checks, it is important to test objects for conformance with the public interfaces of their roles, and for proper integration with their inheritance hierarchies.
“Tests should document the existence of roles, prove that each of their players behave correctly, and show that dependents interact with them appropriately”.
Pragmatically, this means writing test cases that assert whether objects implement the specific messages defined in their roles’ public interface and those that their superclasses expect from them.
Multiple subclasses will undoubtedly share many of the same tests. In those cases, try to encapsulate the test cases into reusable components that every subclass’s test suite can invoke. Just like in application code, it’s better to avoid repetition.
Testing abstract base classes can sometimes be challenging because they are not supposed to be instantiated. In some languages, it is downright impossible to instantiate classes marked as abstract. For these scenarios, a test-specific subclass can be created with minimal implementation that allows tests to exercise the base class.
To avoid test brittleness, test doubles that play certain roles and inherit from superclasses should also be tested for conformance.

Comparison of Lightweight CSS Frameworks

2022-01-13T00:00:00+00:00

Several months ago I was building a new website and needed a CSS framework. There are many new CSS frameworks around now, so I decided to do several small trial runs and compare them to find the most fitting for our site.

Initially I tried using Foundation, which this site is built on, but I ran into a problem: Foundation and other popular frameworks are powerful, but they have more features than I needed, and they take up too much disk space for a modest website. Foundation is about 6000 lines long and 200kB unminified. It can be shrunk by removing components you don’t need, but the time it takes to slim a large CSS framework down to your needs can be more than it’s worth, especially if you want to change any styling.

Instead of adapting a larger framework to my needs, I looked into lightweight CSS frameworks. These aim to provide boilerplate components, better styling for buttons, forms, tables, and the like, all at the cost of very little disk space.

I like to modify the source CSS as needed, so all of the sizes I list will be unzipped and unminified. They are also from my brief real-world testing on one machine, so your mileage may vary.

Bulma

Bulma looked very attractive at first. It has sleek, modern design and is quite popular, with a good-sized community for support. But for our site, it was still too big. I only used a few components and layout helpers, a fraction of its 260kB — around 50kB bigger than Foundation, in my tests!

mini.css

mini.css had some great things going for it, but got pushed out by even smaller options which I’ll cover shortly. It took up about 46kB with all the bells and whistles.

The use of flex is a bonus, but it’s a little too style agnostic for the website I was working on; I would have overridden a lot of its styling, making the overhead size even larger.

It has options for using SCSS or CSS variables, which I always like to see. I prefer SCSS’s added features and variables, but if you would rather use vanilla CSS, mini.css has a plain option using CSS variables, which I don’t see too often.

Pure.css

Pure.css offers similar features to the other frameworks on this list, and weighing in at around 17kB, it competes well in size. However, I wasn’t a big fan of its look, and with some odd omissions, notably, the absence of a container class for horizontally centering content, it was edged out by the competition.

Skeleton

Skeleton has very clean styling and a good selection of minimal components. It’s tiny, weighing in at 12kB. Unfortunately, it hasn’t had a release since 2014, and uses float instead of Flexbox, which took it out of the running for building a more modern site.

Milligram

Milligram feels like a spiritual successor to Skeleton: It covers a similar scope, and has a simple, clean design reminiscent of Skeleton’s. In lieu of using classes, it usually applies styling directly to HTML tags. This is a choice I like, since I don’t follow the Tailwind CSS approach of creating websites purely in HTML, with agnostic classes applied to the layout.

It also has an SCSS offering, so it’s easy to drop components you don’t want, making it even tinier!

The size and simplicity of Milligram made it win the bid. It has worked quite well, providing just enough framework to be useful for small websites, but getting out of the way so that you can do your own styling.

Making the most of your lightweight framework

Hopefully this post will give you an idea of what each of these frameworks is like, but the best way to test them is by trying them yourself! These five were fairly quick to spin up and test out on the website I was working on, and doing the same will give you the best idea of what your website needs.

With frameworks that are only a few kilobytes, you can also read through the entire source. I tried to look through enough of each framework’s CSS files to become familiar with its way of doing things. This eased the whole website-building process, and will help you find a framework that matches your style of web development.

Also see my colleague Afif’s article Building responsive websites with Tailwind CSS for an in-depth look at Tailwind CSS.

Building responsive websites with Tailwind CSS

2021-12-03T00:00:00+00:00

Tailwind CSS is a CSS framework, like Bootstrap, Bulma, and Foundation. However, Tailwind does things in a less conventional way when compared to traditional CSS frameworks. Instead of providing CSS classes based on components or functional roles (e.g. .card or .row), Tailwind only provides utility classes, in which each class does only one specific thing a CSS attribute usually does, such as m-4 for margin: 1rem or mt-8 for margin-top: 2rem.

In Bootstrap, one can simply apply the provided .card CSS class to have a <div> styled like a card the Bootstrap way. In Tailwind, the styles have to be constructed with a string of different atomic classes. E.g. the equivalent of a Bootstrap’s .card would be something like relative flex flex-col break-words bg-white bg-clip-border min-w-0 rounded border. Verbose, yes, but this gives flexibility for the developers to define the appearance of a .card element themselves (e.g. there could be multiple variants of appearances of a .card) without having to worry about overriding inherited/cascading CSS classes, which are typically the cause of many CSS bugs in production.

Atomic CSS

The first thing most notice when developing with Tailwind is how wordy CSS class lists can get. It feels almost like using the style="" attribute to write CSS. In the traditional approach to CSS, suppose there are two elements with identical margins:

.card {
  display: block;
  margin: 1rem;
}

.container {
  margin: 1rem;
}

Here, we can see that margin is declared twice. Those duplicates are going to be a few extra bytes in the final CSS payload.

With Tailwind, however, this is how the equivalent would be written:

<div class="block m-4">
</div>

<div class="m-4">
</div>

Here, both of the <div>s are reusing the same class m-4, which is provided out-of-the-box by Tailwind. This approach ensures that the project’s CSS does not grow, which is important for good user experience. Constructing the CSS of a page is a render-blocking task in a web page load. So, the bigger the CSS, the longer the wait time for a user to see something on the browser. Yes, the HTML payload will grow, but just by a little.

One of the differences between using Tailwind CSS classes and using style attribute is that the latter cannot be used to style pseudoclasses (e.g. :hover, :disabled). With CSS classes, that is achievable, but there are special prefixes that Tailwind provides for each of the variants to take effect.

For example:

<!-- margin: 1rem by default, margin: 2rem on hover -->
<div class="m-4 hover:m-8"></div> 

<!-- white background by default, light gray background when disabled -->
<input class="bg-white disabled:bg-gray-100"/>

Keep in mind that not all variants/pseudoclasses are supported by default, as this would make the development output of a Tailwind CSS file really big to cater all of the possible variants. To have them supported, it has to be configured inside the project’s tailwind.config.js:

// tailwind.config.js
module.exports = {
  variants: {
    extend: {
      backgroundColor: ['active'],
      // ...
      borderColor: ['focus-visible', 'first'],
      // ...
      textColor: ['visited'],
    }
  },
}

Or, if the project is on Tailwind CSS v2.1+, the developers can enable Just-in-Time mode, which grants access to all variants out-of-the-box while also being more functional in development mode.

See Just-in-Time mode for more details.

Shaking off the unused CSS

By default, Tailwind will be loading the whole Tailwind CSS project files, with CSS declarations on almost every possible CSS rule. There are a lot in there that a developer might never use. To put that into context, there are 105 different values just for grid and flexbox gaps. Most projects aren’t likely to use them all, so Tailwind needs a way to remove the unused CSS when generating the final CSS build for production use.

This is where PurgeCSS comes in. PurgeCSS is a plugin that analyzes all CSS, HTML, and JavaScript files in the project and removes unused CSS declarations from the final build. This tool is available as a PostCSS, Webpack, Gulp, Grunt, or Gatsby plugin.

Because PurgeCSS analyzes the project’s source code to find exact matches of a given CSS style, a CSS class cannot be used through string concatenations or PurgeCSS will not be able to detect that the given Tailwind class is used.

// SomeComponent.jsx
const SomeComponent = (props) => {
  return (
    <div className={'text-' + props.color}>
      Some text
    </div>
  )
}

// <SomeComponent color='gray-400'/>
// In this case, `text-gray-400` will be removed by PurgeCSS in the final CSS 
// production build because it does not know that the component is using it.

DRYing it up

Suppose we have two cards on the page and we want their appearance to be consistent. In the traditional CSS approach, both these two cards will just have the .card CSS class, and the same styles would be applied to both of them. In Tailwind we can’t do that, however, and it doesn’t make sense to be repeating 7 or 8 or more different class names on both HTML elements on the page.

const AppButton = () => (
  <button className='py-2 px-4 font-semibold rounded-lg shadow-md'>
    I'm a button
  </button>
)

// Just use <AppButton> everywhere and their appearances will be consistent
// No need to repeat the CSS classes for all three components
render(
  <Form>
    <AppButton/>
    <AppButton/>
    <AppButton/> 
  </Form>
)

Therefore, Tailwind can be easier to implement in component-based frameworks, such as Vue or React. But even if you’re not using any of them and are just building a plain HTML file, Tailwind provides a way to compose these classes together by using @apply:

.button {
  @apply py-2 px-4 font-semibold rounded-lg shadow-md;
}

.button.success {
  @apply py-2 px-4 font-semibold rounded-lg shadow-md text-white bg-green-400;
}

Then, .button and .button.success classes will be available to us for reuse as in traditional CSS.

<!-- py-2 px-4 font-semibold rounded-lg shadow-md gets applied when using "button" -->
<button class="button">I'm a button</button>

<!-- py-2 px-4 font-semibold rounded-lg shadow-md text-white bg-green-400 gets applied -->
<button class="button success">I'm a green button</button>

Building a responsive page using Tailwind

Now let’s look at responsive design. Suppose we want to implement a page with a navigation bar, a sidebar, a content area, and a footer:

And the sidebar and content area should collapse into one column on mobile devices, like this:

First, let’s have the basic page layout:

<nav class="p-4 bg-gray-100">
  <ul class="flex gap-2 justify-end">
    <li>Home</li>
    <li>About</li>
    <li>Contact</li>
  </ul>
</nav>
<div class="flex flex-col">
  <aside class="flex items-center justify-center p-4 bg-red-100">
    Sidebar
  </aside>
  <main class="min-h-screen p-4 bg-green-100">
    <p>
      Sit eos nam quam nemo qui. Quas recusandae praesentium ratione incidunt sunt commodi labore Nemo nemo error molestias saepe ducimus? Porro reprehenderit voluptatibus nihil voluptate quia. Voluptatibus autem maiores vero?
    </p>
    <p>
      Consectetur veniam voluptate esse amet debitis eius? Voluptatem officia quibusdam voluptates cum rerum Odio rem maiores laborum commodi cum. Nobis numquam quia nemo maiores repellendus error fuga Repellendus consequatur laudantium?
    </p>
    <p>
      Elit vitae sit reprehenderit sit laboriosam Ratione iusto numquam corrupti ullam libero! Nisi veritatis facere repudiandae eos perspiciatis recusandae veritatis. Cupiditate temporibus repellat tempore optio numquam id! Perferendis maxime unde
    </p>
    <p>
      Dolor autem dolore tempora atque provident. Maxime quos ipsum porro non suscipit. Consectetur et perspiciatis perspiciatis illum quos Ab nostrum unde facere nemo mollitia, saepe ab? Vitae tempore hic accusamus
    </p>
    <p>
      Elit labore odit error pariatur cupiditate Ex sequi accusantium maxime et vero Unde quo laboriosam illo ipsam modi eaque Delectus dolorem quas quidem reprehenderit fugiat! Exercitationem provident voluptatum perferendis ut.
    </p>
  </main>
</div>
<div class="p-4 bg-yellow-100">
  <h5 class="font-bold">Footer links</h5>
  <ul>
    <li>Home</li>
    <li>About</li>
    <li>Contact</li>
  </ul>
</div>

Tailwind official documentation recommends taking a mobile-first approach. Hence, all classes without any screen-size variants will be applied to all screen sizes. Tailwind then provides several screen-size variants such as sm, lg, xl, and 2xl that can be used to control the appearance on specific screen sizes range.

This is what we’re doing here. As you can see, we’re using flexbox layout to collapse all elements down to a single column.

Responsive variants

Now, let’s add Tailwind’s responsive variants so that the page is responsive to screen sizes. In our case, what we would want is to have aside and main placed side-by-side when there’s enough real estate on the screen. To achieve that, we would need to switch the flex-col class to flex-row on bigger screen sizes.

<div class="flex flex-col md:flex-row">
  <aside class="flex items-center justify-center p-4 bg-red-100 md:flex-none md:w-1/3 lg:w-1/4">
  <!-- sidebar -->
  </aside>
  <main class="min-h-screen p-4 bg-green-100">
  <!-- main content -->
  </main>
</div>

flex-col md:flex-row here does the trick for us. md variants, by default, kick in when the screen width is at a minimum of 768px. At that point, our flexbox will change from the column layout to the row layout, displaying our aside and main elements side-by-side in one row. To better distribute the width, we specify md:w-1/3 and lg:w-1/4 classes to the sidebar. w-1/3 and w-1/4 sets the width of the elements to one-third and one-fourth of the parent container respectively. The md and lg variants both control at what screen sizes should Tailwind apply which styles.

Conclusion

It can be a bit daunting to start, but once you get a handle on it, Tailwind CSS is a great option for rapidly building user interfaces with total control over the styles. Unlike other frameworks, Tailwind does not attempt to provide a default styling of any component, allowing every site that uses Tailwind to be truly unique from another.

These responsive variants can be applied to any other CSS class from Tailwind, providing a powerful way to build responsive user interfaces. The very thin abstraction over CSS provides developers with a greater flexibility and control over the design while being a good constraint to guide the development process.

Happy styling!

Converting to Hugo

2021-08-23T00:00:00+00:00

We recently converted the End Point website from Middleman to Hugo. I’ll go into more detail shortly, but the general result has been much better build times with less configuration and better support for local development.

Background

In 2017 we converted this website from a Ruby on Rails app to a static site. With tons of high-quality static site generator options, we could implement the shiny features used by our Rails site in 2009 with less overhead and quicker load times.

We also wanted to move away from Blogger to self-hosting our blog, using GitHub issues for comments. We ended up switching to Middleman, a static site generator written in Ruby, and had a mostly positive experience. Ruby was a good fit switching from Rails, and (if I remember correctly) Middleman had pretty competitive performance.

With over 1000 blog posts at the time, as well as lots of other pages, our site was quite slow to build—3.5 minutes when building with the full blog.

Middleman had a nice development server, but due to some server-side rewrites, we couldn’t use it. Instead, we got around the build times by writing a simple Ruby script to generate an HTML preview, letting our blog authors see what their post would look like, more or less. This worked okay, but was not 100% accurate and made copy-editing and formatting slower than it needed to be for us “Keepers of the Blog”.

We started hiding most of the blog from Middleman while building to save time, but build times were still 40 seconds or more. With our patience for long build times waning, as well as Middleman losing most of its support in the development and user community, we decided to get in the market for a new site generator.

Shopping around

Before we (🚨 spoiler alert 🚨) settled on Hugo, we tried using Zola, a site generator written in Rust and boasting tiny build times. Zola is a small project, and would have worked fairly well for us, but it had several downsides.

Initial build times were very promising, but slowed down more than expected after adding our now more than 1500 blog posts. We still ended up with very respectable build times of less than 15 seconds.
As far as I could tell, Zola would have required an _index.md file in every section and subsection, to hold section settings or to make it a transparent section, passing its files to the parent section. I didn’t like the sound of having a couple hundred extra Markdown files, one for every blog year and month.
At the time of writing, Zola doesn’t support custom taxonomy paths. That means we would have our blog tags at www.endpointdev.com/tags/, instead of our existing (and preferred) www.endpointdev.com/blog/tags/. This has been discussed on Zola forums, but seems to have stalled. This wasn’t a complete dealbreaker, but it was disappointing.

Making the switch to Hugo

We wanted to see if there was another option which solved our issues with Zola. I decided to try Hugo. It’s written in Go and is currently one of the most popular static site generators.

I partially converted the site and blog, and found that Hugo solved our main concerns with Zola:

Build times were close to twice as fast as Zola.
You can dump as many subdirectories as you want in each section, and they’ll still belong to the section but retain the original directory structure.
Hugo supports custom taxonomy paths through its permalinks.

We were also able to shave off a lot of build time by analyzing our template metrics—this is one of my favorite features in Hugo.

Local development

So far, we’ve had extremely smooth local development. Hugo (like Zola) comes as a standalone single executable, so it’s extremely easy to get started or update. This was a huge improvement over Middleman, which required a heap of Ruby gems and plugins. Now every blog author can easily clone our repo, run the development server, and edit their post directly, with the full site building in anywhere from ~10 seconds all the way down to ~2 seconds, depending on the author’s machine.

For blog authors, we were using a fork of an abandoned Middleman plugin. With Hugo, we’re using their taxonomies, which have been fairly easy to set up. We were also able to use Hugo’s built-in Chroma highlighter, instead of loading and running highlight.js on every blog page.

Some drawbacks

July 2025 Update: Hugo has seen a lot of development since this post was written in 2021. I’ve added Wayback Machine links so the references are historical, but these examples are out of date now. From my usage in the past few years, the documentation has improved quite a bit.

We’re loving the wonderfully fast build times and easy local development. I like the templating fairly well, and the simple configuration is wonderful. But Hugo does have several issues and missing features I’d like to see.

One place Zola wins over Hugo is the ability to easily print the entire context in a big JSON object. It’s a bit hard to navigate, but in my experience much easier and clearer than Hugo, where I have to either try using printf to display the context’s variables, or search through the documentation. This was one of my favorite ways to quickly debug and learn about the inner workings of Zola, and would be very welcome in Hugo as well, without needing to know Go formatting width and the full shape of Hugo’s context object beforehand.

Joe Mooring, a Hugo developer, mentioned that you can print some things with debug.Dump. I tried passing the context with {{ debug.Dump . }}, which worked well for seeing what context variables are available/set.

Documentation is another area where Hugo struggles sometimes. Pages often don’t feel interconnected and examples are often lacking. Here are a few examples I encountered:

The Hugo Pipes page SASS/SCSS shows how to transform Sass files to CSS, but did not link to the very useful Page Resources page. It turned out I just needed to link to {{ $style.RelPermalink }}, but as a new user it wasn’t clear that the CSS file was considered a Resource. Having more links to related pages or more examples could save a lot of headaches for newbies.
Lookup Order says under the Layout section that it “can be set in page front matter,” but I had to look under Front Matter to see that layout is the key name. A small change, and didn’t take long to experiment and find out, but especially since YAML is case sensitive, having a link to the actual front matter key would be better.
Enabling custom outputs on a per-taxonomy basis does not seem to be possible. We want to generate Atom feeds for our blog tags, but not for our blog authors, both of which are taxonomies. As far as I can tell, we have to enable them both and live with the cruft of unnecessary blog author feeds being generated.
Joe also provided a solution to this problem: cascade the outputs front matter field down from the taxonomy page (e.g., content/tags/_index.md) or from your site configuration.
- https://gohugo.io/configuration/cascade/
- https://gohugo.io/content-management/front-matter/#cascade-1
I tested this and it works like a charm.

Onward and upward!

It may look (mostly) the same, but on our end it’s never been easier to write blog posts or update the website, thanks to Hugo and all its contributors!

National Braille Press Releases Redesigned Website

2019-08-28T00:00:00+00:00

End Point congratulates National Braille Press on the recent release of their redesigned website, launched earlier this week! National Braille Press (NBP) supports the blind and low-vision community with events, initiatives, resources, children’s programs, and a bookstore. NBP has been working with End Point since 2002 and hosts and maintains their website, which is based on the Interchange open-source ecommerce platform.

Project Phases

End Point started working with NBP on this redesign project in late 2017. We began with a user experience (UX) review & content strategy project which resulted in design directives for our in-house team. Design and plans were completed in mid-2018 and implementation began then. End Point built a new, more powerful search feature and developed a number of ‘cornerstone’ pages while NBP staff worked tirelessly in-house to convert the rest of the pages on their website to the new designs.

Leveraging NBP In-House Resources

NBP’s wide reach in their community and long history means their website has hundreds of content pages. This can be costly to convert, and for some non-profits, can make a redesign project cost-prohibitive. End Point engineers Greg Davidson and Marco Pessotto worked alongside NBP staff helping them learn the Bootstrap web development toolkit and the steps they needed to take to integrate each page into the new designs. Using these in-house resources dramatically reduced the overall project cost while allowing the content to be converted carefully by hand with accuracy and care.

WCAG 2.0, AA Standard

NBP’s user base is heavily centered in the low-vision community, so compliance with user accessibility standards was a main focus of the redesign effort. End Point worked with NBP to make sure all of the engineers on the project were trained in the Web Content Accessibility Guidelines (WCAG 2.0) AA standards and guidelines. Testing for compliance was done with AXE and WAVE Chrome accessibility plugins. NBP also completed direct user testing with screen readers and devices.

Congrats again to NBP on completing this project with us!

Expert Help with Your SaaS System

2018-04-23T00:00:00+00:00

Are you thinking about starting a new website and using BigCommerce, Shopify, or WooCommerce? The software-as-a-service offerings on the market today can help you get a great-looking, low-cost ecommerce website up and running quickly, but you may need more help than you first expect.

In order to get the most out of your site, ecommerce consultants like us at End Point can guide you through setup, customize your site to fit your brand, manage all of your technical requirements, and help drive traffic to your site. This post is an overview of services we offer to clients looking for a SaaS solution.

Select the Right Vendor

Working with an expert consultant can help you make the right choices from the start. Sometimes knowing the level of customization that your project requires can be a real challenge. End Point has experience with everything from out-of-the-box SaaS platforms to large-scale, custom software developments—we take time to understand your requirements and guide you to the perfect solution for your business.

Custom Design

Most SaaS offerings include ready-to-use, beautiful design templates, but you’ll often find that they require some tweaking. We can customize your design so that it fits perfectly with the look and feel of your brand, without the time and expense of going through the design process from scratch.

Working with an ecommerce consultant that has experience with user behavior, site navigation, and business workflows can help you develop the best way to organize your pages and products. With improved navigation, we can ensure that your users are finding what they’re looking for and getting where they’re going quickly and seamlessly.

Customizing Your Store

Customizing your store to work with your specific needs, like shipping integrations, 3rd party apps, and APIs can be a challenge. End Point can help you research the solutions already in place, or build custom solutions for your site.

Email Setup

End Point can help you set up your email on your desktop or in the cloud, and can help you configure and maintain all of your in-house email needs.

DNS and Domain Names

End Point has DevOps experts who can make sure everything with your domain name and DNS changes is handled quickly and correctly during the setup or migration of your site from one provider to another.

Search Engine Optimization (SEO)

A solid search engine optimization strategy is critical to the success of your website, and therefore critical to the success of your business. A high Google ranking means more page views—and more conversions. At End Point, we design and build with SEO in mind from the start to help you get the most value from your online presence.

Payments and Merchants

End Point has experience with many major merchant vendors. We can help you find the right merchant, be it PayPal, Stripe, Authorize.net, Braintree, etc. We can make sure that payments are set up, tested, and integrated into your business cash flow. We also have experience with PCI compliance and can help you step through an evaluation or mitigation process and get your system in tip-top shape.

Project Management

Are you trying to wrangle a team of people? Your old vendor and your new one? Do you need help in managing the project? Our project managers are here to help you meet your business goals and get to the finish line on time and within budget.

System Migrations

Working with an expert consultant can really help when you are moving from one system to another. We have customizable data export and import scripts and many automated tools to move your content to your new platform and can save you hours of moving products and pages by hand.

Summary

Working with a consultant agency can really give your SaaS project the professional edge you’ll need to compete in today’s ecommerce market. We offer consulting packages to fit your budget and the depth of services that you need. Talk to us today about how we could help get your project off the ground.

(Jon Allen co-authored this article.)

Designing for SEO from the Start

2018-03-28T00:00:00+00:00

Search engine optimization (SEO) is critical to the success of your website, and therefore critical to the success of your business. A high Google ranking means more page views—and more conversions. Google rewards websites that are user-friendly and easy-to-navigate, with fresh content and frequent updates. At End Point, we design with SEO in mind from the beginning of the project to help you get the most value from your online presence.

These are the five main areas that we focus on to improve your ranking:

Content Strategy—You want to provide your users with quality content. We can provide a content strategy to help ensure that your site stays on target, with clear copy, focused messaging, and consistent branding. We’ll help you put together a site that gets visitors where they want to be—and you’ll reap the rewards with an increase in traffic to your site.
Sitemap, Keywords, and Semantic Markup—We dive into the nuts and bolts of your site to make sure that it can be crawled and indexed easily by Google. We produce a prioritized XML sitemap, relevant, long-tail keywords and metadata, descriptive page headings, titles, and URLs. Your site’s code will utilize HTML5 semantic markup to produce a well-structured, hierarchical document that will be easily read by web crawlers—and humans, too.
Blogging and Social Media—Keeping your website fresh with new links and content is critical for SEO success. Setting up a blog platform makes it easy to quickly generate new content that can draw more visitors to your site. We can also connect you with social media platforms such as Twitter and Facebook to help carry your messages across the web.
Analytics—Google Analytics allows you to watch in real time how users are finding and interacting with your site. Figure out which pages perform the best, which are underperforming, identify trends in user behavior, and calibrate your site to help users get the most out of their experience.
Mobile Support—With just over half of all web traffic coming from mobile devices, it’s crucial to have a website that’s responsive on any device. Because of the ubiquity of mobile browsing, Google rewards sites that are mobile friendly. We optimize your site to ensure that pages load quickly and display on any laptop, tablet, or smartphone.

There’s no big secret to a strong SEO strategy. It’s all about having engaging, useful content that’s easy to find and navigate. End Point has the knowledge and resources to help your business grow by building you a site that’s clear and focused, and one that’s up to the latest web standards.

Here are a few guides that provide more details about what goes into a strong SEO strategy:

The End Point Design Process

2018-03-14T00:00:00+00:00

Designing for the web means more than just creating beautiful websites—whether it’s a marketing site, an ecommerce platform, or a large-scale web application, thoughtful design means better, more intuitive user experiences. The design process provides a roadmap for developers and a shared set of expectations for the clients of what the final product will be.

If you’ve contracted End Point for design work, or you’re considering it, this post will show you all the steps as we go from an initial concept to a polished design that’s ready for development. You’ll also learn the basic vocabulary of deliverables and some of the tools involved in the process.

Phase I: Discovery

Every new app, website, or product starts with an idea. The initial phase of design work means clarifying that idea—defining its boundaries and goals. Thorough research and investigation are critical for setting the path to success. We interview our clients’ staff, stakeholders, and users to get a comprehensive picture of the current marketplace, discover any pain points in existing workflows, and learn what we can do to make things better. We also take an in-depth look at existing content and, with the client, decide what should stay, what should go, and what needs to be updated or refreshed.

At the end of this process, we provide our clients with a new sitemap, interview transcripts, and a detailed strategy document. Depending on the client’s needs, we may also produce user flow diagrams, user personas, taxonomies, and a content migration plan.

Phase II: Sketching and Wireframing

Once the research materials have been gathered, content has been analyzed, and a design strategy is in place, we make sketches, diagrams, and rough mockups so that everyone involved in the project can start to see the overall form of the final product. At this stage, concerns about font, color, or graphics are mostly off the table—we’re focused on how the parts of the application fit together to create a great user experience.

Wireframing at End Point is generally done using Balsamiq, a dedicated wireframing application, or Sketch, a more powerful design program that allows the wireframes to be developed into fully-realized design comps.

Phase III: Design Comps

Often, the wireframes are all a developer needs to begin building an application. If a project has an existing design vocabulary, there may be no need to go further. But if an all-new application or website is being built, then a designer will articulate all of the elements needed to create a custom look and feel—color, typography, graphics, and more. Interface design isn’t just decorative—clear labels, semantic colors, eye-catching CTAs (calls to action), and a well-considered hierarchy of page elements all serve to guide the user through the system efficiently and effectively.

Design comps are presented as a multi-page PDF that shows the client what primary screens of the application will look like. These are created in Adobe Illustrator or Sketch, which both allow for pixel-perfect designs that correspond exactly to the finished product.

Phase IV: Handoff

Once the client has approved the final designs, they’re ready to move to the next stage of the process, where frontend and backend developers turn the finished designs into fully-functional, working software. As development continues, the designer is on hand to help guide the building of the interface and ensure that the design specifications are maintained.

Looking for help realizing your next project, big or small? Get in touch with us to obtain a copy of our design portfolio, and to find out what End Point can do to turn your next big idea into a reality.

Series Digital joins End Point!

2017-06-01T00:00:00+00:00

End Point has the pleasure to announce some very big news!

After an amicable wooing period, End Point has purchased the software consulting company Series Digital, a NYC-based firm that designs and builds custom software solutions. Over the past decade, Series Digital has automated business processes, brought new ideas to market, and built large-scale dynamic infrastructure.

Series Digital launched in 2006 in New York City. From the start, Series Digital managed large database installations for financial services clients such as Goldman Sachs, Merrill Lynch, and Citigroup. They also worked with startups including Drop.io, Byte, Mode Analytics, Domino, and Brewster.

These growth-focused, data-intensive businesses benefited from Series Digital’s expertise in scalable infrastructure, project management, and information security. Today, Series Digital supports clients across many major industry sectors and has focused its development efforts on the Microsoft .NET ecosystem. They have strong design and user experience expertise. Their client list is global.

The Series Digital team began working at End Point on April 3rd, 2017.

The CEO of Series Digital is Jonathan Blessing. He joins End Point’s leadership team as Director of Client Engagements. End Point has had a relationship with Jonathan since 2010, and looks forward with great anticipation to the role he will play expanding End Point’s consulting business.

To help support End Point’s expansion into .NET solutions, End Point has hired Dan Briones, a 25-year veteran of IT infrastructure engineering, to serve as Project and Team Manager for the Series Digital group. Dan started working with End Point at the end of March.

The End Point leadership team is very excited by the addition of Dan, Jonathan, and the rest of the talented Series Digital team: Jon Allen, Ed Huott, Dylan Wooters, Vasile Laur, Liz Flyntz, Andrew Grosser, William Yeack, and Ian Neilsen.

End Point’s reputation has been built upon its excellence in e-commerce, managed infrastructure, and database support. We are excited by the addition of Series Digital, which both deepens those abilities, and allows us to offer new services.

Talk to us to hear about the new ways we can help you!

Case Study: Responsive Design Return on Investment

2016-07-21T00:00:00+00:00

Responsive design has been a hot topic in the e-commerce world for several years now. End Point has worked on many sites over the last few years to transition clients to a responsive design website model. While many large sized retailers have already transitioned to a responsive design, there are many smaller e-commerce sites that are still on an older design model and I would like to show that the return on investment for those stores is still noteworthy.

The lead of our Interchange team, Greg Hanson, led a responsive design project and I’d like to summarize that work on our blog. For confidentiality, I am leaving out the client’s name in this case.

Why Go Responsive?

There are two main reasons every e-commerce website, even a small one, needs to become responsive:

Your customers
Google

The march toward mobile sales at this point is undeniable and unstoppable. As more and more people become comfortable using their phones and tablets to purchase things, the bigger this market share will become. Also, Google has begun de-prioritizing websites that do not cater to mobile users. If you are waiting to go responsive because of budget, you might surprised to learn how dramatically the mobile revenue increased for the customer in this case.

Goals

This client is a small e-commerce business with a heavy ‘on’ season and ‘off’ season where the business owners could focus on this project. They wanted:

To accommodate the increasing mobile user base; they knew it was there from looking at their Google Analytics.
To increase revenue from mobile users. They could see that they had a 10% mobile user base, but they were converting only a small percentage.

End Point’s strategy

Our strategy with this small client, to minimize impact to the business and cost was to:

Use Bootstrap

Bootstrap is one of many front end frameworks that allows you to create a design template and roll that out to all the pages within a website without having to re-code each and every page in a website. This dramatically increases the speed and decreases cost.

Break up the work into segments

In this case, we had a three phase approach:

Phase I, redesign the site using Bootstrap but still at fixed width
Phase II, site checkout sequence changed to responsive
Phase III, entire site responsive

The Project

Converting the site to Bootstrap was the biggest chunk of the time and money spent on this project. Since we knew this would be the foundation for the changes to come, we took our time getting it right, keeping the client involved every step of the way. We didn’t want to get in the way of their busy season either, so we completed that project and waited a half a year to begin the next piece.

The second step was updating checkout sequence to be responsive since this was arguably the hardest part about using the non-responsive site on a mobile device. The client considered this piece top priority. Plus, since it was only a few pages, it allowed us all to better understand the scope of coding the rest of the site and give the client an accurate picture of the budget.

Last, once we had a responsive checkout sequence, we changed the rest of the internal pages to be responsive and rolled out the entire site as responsive and mobile friendly.

Results

The first time we looked at the analytics following the responsive conversion, we were shocked! Using a small sample period, from just a year prior, we saw a 280% increase in mobile purchases.

The timeframe for these comparison numbers was August 2014 before the responsive transition and August of 2015, after the transition.

To sanity check those numbers, we just re-ran some of the analytics recently and in May of 2016, revenue from mobile users is still up over 90% and the clients total revenue year-over-year is up 12%.

We also ran some numbers on the growth of mobile revenue as a percentage of overall revenue through this process. As you can see, two years ago mobile revenue was less than 1% and is now near 12%.

In this case, I didn’t go into all the ways to slice and dice the numbers in Google Analytics. However I’m happy to speak with you if you want to know more about mobile users, this client’s data, or how responsive design might help grow your e-commerce business.

The Lesson

The lesson here is that any store will benefit from going responsive. Having an experienced partner like End Point that can work with your budget and timeline can make this is a doable project for any size store and budget.

Hue’s on First: How we used responsive bulbs to join software and hardware for a busy medical practice

2016-03-14T00:00:00+00:00

In 2014 we began working with a busy bariatric surgery office in Long Island to create a system that would allow the practice to better manage doctor paging and patient wait time. By placing a responsive, color-coded light bulb and tablet outside each examination room, the staff could see which rooms were empty, which were occupied by a patient waiting on a specific doctor, and in which a doctor-patient consultation was in process. Outside each room is a tablet with information including the patient number, the attending doctor’s name, and the wait time.

In addition to providing a comprehensive, granular paging service for doctors, Fast Track also provides feedback to the practice. This feedback includes average patient wait times per doctor, per time of day, and per procedure. This allows the practice to make necessary changes and increase patient satisfaction and peace of mind.

I asked Danny Divita, one of the main developers on this project, to tell us more about the Hue/ FastTrack interface.

LF: Describe the project for which we used Hue bulbs. What were all the pieces that needed fitting together?

DD: The Hue bulbs are being used for a bariatric clinic to alert the staff when pages are sent to of pages to specific rooms. Alongside the lights the API also has to work with a RF device-locating API. The RF API had to be coordinated with the Hue light API to coordinate changing colors, alerts, and states.

LF: Why were Hue bulbs a good solution for the problem of creating an easy-to-understand, integratable visual alert system? Did you consider any alternatives?

DD: From a cost perspective and ease of integration the bulbs were a good solution for this project. There are other solutions, but they are more costly and the integration would have taken longer.

LF: How did you hear about Hue bulbs? Was the API easy to access and work with? How was using Hue’s testing environment?

DD: The client suggested the bulbs during their research before having us develop their application. The API is extremely easy to work with and well documented. The Hue API has a built-in testing feature that made it easy to understand the API and develop around it.

LF: What was the most difficult thing about integrating this technology? Can you think of any other commercial implementations of these bulbs? Specifically in the medical industry?

DD: The most difficult aspect was trying to come up with a good alert (blinking) feature. The API has some built in alerts, but they are limited to a set timed interval. We had to develop around this to ensure the alerts stayed constant and did not time out. Another application for these lights in the medical field could be to indicate severity of a situation or condition. Because the lights can change color, the applications can signal the proper response for the staff.

LF: Did you write any new software for this project? Is that work available to other developers?

DD: We used a third party library that helps to manage stateless workflows. Our application expanded upon this library to design a workflow engine that manages paging the staff, Hue lights, and RF device locating.

Full Screen Gallery with Supersized and video slides

2016-01-26T00:00:00+00:00

I was recently looking to build a full screen image and video gallery for our client Mission Blue. Something similar to the Google Maps interface you can see in the screenshot below:

After scouring the Internet to find a suitable jQuery plugin I finally decided on Supersized, Full screen background slideshow plugin for jQuery.

After downloading the library, include it on the page:

<link href="/wp-content/plugins/wp-supersized/theme/supersized.shutter.css?ver=4.2.2" id="supersized_theme_css-css" media="all" rel="stylesheet" type="text/css"></link>
<script src="/wp-includes/js/jquery/ui/effect.min.js?ver=1.11.4" type="text/javascript"></script>
<script src="/wp-content/plugins/wp-supersized/js/jquery.easing.min.js?ver=1.3" type="text/javascript"></script>
<script src="/wp-content/plugins/wp-supersized/js/jquery.easing.compatibility.js?ver=1.0" type="text/javascript"></script>
<script src="/wp-content/plugins/wp-supersized/js/jquery.animate-enhanced.min.js?ver=0.75" type="text/javascript"></script>
<script type='text/javascript' src='/wp-content/plugins/wp-supersized/js/supersized.3.2.7.min.js?ver=3.2.7'></script>

Basic functionality

Let’s create a variable that will hold all the images in the slideshow:

var images = [];
images.push({
  type: 'IMAGE',
  image: 'img1.jpg',
  title: 'Image 1',
  thumb: 'img1_thumb.jpg',
  url: 'https://www.endpointdev.com'
});
images.push({
  type: 'YOUTUBE',
  image: 'screenshot1.jpg',
  title: 'YouTube slide',
  videoid: 'abc12345678',
  thumb: 'screenshot1_thumb.jpg',
  url: 'https://www.youtube.com/watch?v=abc12345678'
});

Let’s initialize Supersized:

jQuery.supersized({
  slideshow: 1,
  autoplay: 0,
  min_width: 0,
  min_height: 0,
  vertical_center: 1,
  horizontal_center: 1,
  fit_always: 0,
  fit_portrait: 1,
  fit_landscape: 0,
  slide_links: 'blank',
  thumb_links: 1,
  thumbnail_navigation: 1,
  slides: images,
  mouse_scrub: 0
});

<div id="thumb-tray" class="load-item">
  <div id="thumb-back"></div>
  <div id="thumb-forward"></div>
</div>
<div id="slidecaption"></div>

Customizing the screen image size

I didn’t want to have the full screen image as it was a little overwhelming for the user. I wanted the black bars just like in the Google interface. Supersized allows for easy customization. This CSS did the trick:

#supersized, #supersized li {
  width: 70% !important;
  left: 0 !important;
  right: 0 !important;
  top: 1px !important;
  margin:auto;
}

Introducing video (YouTube) slides

First, I added the Youtube API:

<script type="text/javascript" src="https://www.youtube.com/iframe_api"></script>

Then I added a couple of CSS styles:

#supersized .player {
  margin: auto;
  display: block;
}

Finally, I went into the Supersized library source and modified it. To allow for the video slides to appear, I added the new condition and the slide type ‘YOUTUBE’

base._renderSlide = function(loadPrev, options) {
  var linkTarget = base.options.new_window ? ' target="_blank"' : '';
  var imageLink = (base.options.slides[loadPrev].url) ? "href='" + base.options.slides[loadPrev].url + "'" : "";
  var slidePrev = base.el + ' li:eq(' + loadPrev + ')';
  var imgPrev = $('<img src="' + base.options.slides[loadPrev].image + '"/>');

  if (base.options.slides[loadPrev].type == 'YOUTUBE') {
    imgPrev.load(function () {
      var video = $('<div class="player" id="player'+ base.options.slides[loadPrev].videoid + '"></div>');
      video.appendTo(slidePrev);
      var player = new YT.Player('player' + base.options.slides[loadPrev].videoid, {
        height: 390,
        width: 640,
        videoId: base.options.slides[loadPrev].videoid
      });
    });// End Load
  }
  else {
    imgPrev.appendTo(slidePrev).wrap('<a ' + imageLink + linkTarget + '></a>').parent().parent().addClass('image-loading ' + options['class']);

    imgPrev.load(function () {
      $(this).data('origWidth', $(this).width()).data('origHeight', $(this).height());
      base.resizeNow();// Resize background image
    });// End Load
  }
};

Final Result

This is how gallery looks with the customizations:

This is what a video slide looks like:

Hope you found this writeup useful!

Design for the Quotidian. Build for the 100-Year Flood.

2016-01-13T00:00:00+00:00

After years of building software, I’ve crossed over to the design side and spent the last months thinking about UI/UX. In doing so I’ve come to realize that as disciplines, engineering and designing are far afield. Software development challenges you to think of the worst and least likely, whereas design asks you to consider the everyday essence of the thing.

Floods are uncommon, otherwise someone would have knowingly built your home in a river. Floods are what software developers call edge cases, uncommon happenings, and they are the subject of worry for software developers. They are what we build for. What happens when a user accidentally dumps Moby Dick into the field labeled “First Name”? Or, what happens when the hackers come calling; what weakness will they find?

As users of software, people mostly behave as expected, but not always. Like a city planner preparing for a 100-year flood, software developers carefully consider unlikely events—especially when building for large organizations, the Internet, or for a long lifespan. In the fullness of time, all events inhere. The unusual will happen, which is to say that software not engineered for edge cases is eventually hacked, produces inaccuracies, or simply fails. Just as the 100-year flood will in time arrive downtown, so too do the hackers, the accidents, and the failures. And knowing this, uncommon eventualities often come to define a project. (As an example, consider the extreme, One World Trade Center.)

While software may appear to be about banking, chatting, or auctions, it is really about surviving the crazy things users might do. Designers, on the other hand, don’t care about your crazy. They care for expressing the purpose of the thing. Which is to say, they are designing for everyday use, the common cases, for what the thing is supposed to do. As such, design ensures that things look like what they are about. And, that means mostly ignoring how the thing may be misused.

I’m thinking of a butter knife, and how it is so often a poor substitute for a flathead screwdriver. A nicely designed butter knife announces its function, even at the expense of limiting its utility. The designer of the butter knife doesn’t care that the tip is without the torsional rigidity to help you unwind that screw. He cares that it looks like a thing for cutting and spreading butter.

UI/UX design is the same. A well designed application promotes its purpose, instructs, and looks the part. If common use cases require visiting menus labeled “Advanced”, that’s evidence that the designer missed the point of the software. The discipline of design requires us to rank order the software’s primary functions and subsidiary functions. Then we shape the look of the software to preferentially serve the most important functions, the common cases of use. If engineers build from the edges in, designers design from the center out, first thinking of the essential functions. While the developer fortifies the edges, the designer greases the rails so that the application smoothly satisfies the common cases. While engineers ensure the house won’t be washed away by a flood, designers give its layout order and harmony.

Old Dog & New Tricks — Giving Interchange a New Look with Bootstrap

2015-09-02T00:00:00+00:00

Introduction

So your Interchange based website looks like it walked out of a disco… but you spent a fortune getting the back end working with all those custom applications…. what to do?

Interchange is currently being used in numerous very complex implementations. Trying to adapt another platform to replace Interchange is a formidable task, and in many cases the “problem” that users are trying to “solve” by replacing Interchange, can be remedied by a relatively simple face lift to the front end. One of the main attractions to Interchange in the past was its ability to scale from a small mom & pop eCommerce application, to a mid level support system for a larger company and its related back end systems. Once the connection to those back end systems has been created, and for as long as you use those related systems, Interchange will continue to be the most economic choice for the job. But that leaves the front end, the one that your customers see and use (with their phones and tablets) that becomes the most immediate target for “modernization”.

Granted, there are new and alternate ways of accessing and presenting data and views to users, but many of those alternatives are also accessible and inter-operable with Interchange. So while there are several topics that can be investigated at length, we will focus first on a popular front end framework that can help Interchange present a modern responsive theme to the end users. That framework is Bootstrap. Bootstrap is a good basic start for breathing new life into your Interchange application. Bootstrap uses a reasonably generic approach to HTML, CSS, and JavaScript frameworking. This blends nicely with the Interchange application approach: providing a basic, repeatable, broad based and well supported foundation that can then be crafted into whatever the developer and their client may need.

My intent in this post, is to give you links to the tools available to implement Bootstrap into your Interchange application, and in subsequent posts explain our development process which may help you in how you use the tools. Like any development, there are many ways to accomplish various tasks, and knowing why certain things were done, can help.

Alternatively, you may simply want to just download the “strap” catalog, and get started. At the time of this writing, Josh Lavin has been reviewing and refining the package, and the most recent version can be found at his Github account: Bootstrap template for Interchange. It will soon become the standard catalog template in Interchange. So, if you are not really interested in why and how this template was developed, feel free to go to the git repository in the link, clone a copy and get busy! The README is very informative, and if you are an Interchange developer you probably won’t have much trouble implementing this.

If you are interested in some of the major changes that we made to the old “standard” templating approach, and how you can apply those changes to an existing catalog without having to start from scratch, stay tuned in for my next post.

Mobile-friendly sites or bust!

2015-03-23T00:00:00+00:00

A few weeks ago, Google announced that starting on April 21 it will expand its “use of mobile-friendliness as a ranking signal” which “will have a significant impact in our search results”.

The world of search engine optimization and online marketing is aflutter about this announcement, given that even subtle changes in Google’s ranking algorithm can have major effects to improve or worsen any particular site’s ranking. And the announcement was made less than two months in advance of the announced date of the change, so there is not much time to dawdle.

Google has lately been increasing its pressure on webmasters (is that still a real term‽) such as with its announcement last fall of an accelerated timetable for sunsetting SSL certificates with SHA-1 signatures. So far these accelerated changes have been a good thing for most people on the Internet.

In this case, Google provides an easy Mobile-Friendly Site Test that you can run on your sites to see if you need to make changes or not:

So get on it and check those sites! I know we have a few that we can do some work on.

Angular Responsive Layout Directive

2015-01-13T00:00:00+00:00

To all of you window.onResize aficionados, I dedicate this blog post because today we will be doing a lot of dynamic resizing in JavaScript. All of it will be done completely and effortlessly with my one-page long Angular directive.

Why do I need to attach an expensive onResize handler to my already overloaded page, you ask. The answer is very simple. Our app layout is pixel-perfect. Each element has the predefined width and margins. Yet, the app needs to look good on all kind of devices, from regular PC to tablet to iPhone. That’s why I created the following Angular directive in /scripts/directives/tsResize.js:

angular.module('angularApp')
.directive('tsResize', function($window) {
 return function(scope, element) {
   var w = angular.element($window);
   scope.getWindowDimensions = function () {
     return {
       'h': $window.innerHeight,
       'w': $window.innerWidth
     };
   };
   scope.$watch(scope.getWindowDimensions,
              function (newValue, oldValue) {
     scope.windowHeight = newValue.h;
     scope.windowWidth = newValue.w;

     scope.mainContainerStyle = function () {
       if (newValue.w > 890) {
         return {};
       } else {
         val = newValue.w/890;
         return {
           '-webkit-transform': 'scale(' + val + ')',
           '-o-transform': 'scale(' + val + ')',
           '-ms-transform': 'scale(' + val + ')',
           'transform': 'scale(' + val + ')',
           'transform-origin': 'left -10px',
           '-webkit-transform-origin': 'left -10px'
         };
       }
     };

     scope.topBarStyle = function () {
       if (newValue.w > 890) {
         return {};
       } else {
         val = newValue.w/890;
         return {
           '-webkit-transform': 'scale(' + val + ')',
           '-o-transform': 'scale(' + val + ')',
           '-ms-transform': 'scale(' + val + ')',
           'transform': 'scale(' + val + ')',
           'transform-origin': '0 2px 0',
           '-webkit-transform-origin': '0 2px 0'
         };
       }
     };
    }, true);

   w.bind('resize', function () {
     scope.$apply();
   });
  }
})

As you can see all the magic is done with transform:scale CSS attribute on the two of my main page components: the navigation and the contents container.

They styles are cross-browser.

return {
  '-webkit-transform': 'scale(' + val + ')',
  '-o-transform': 'scale(' + val + ')',
  '-ms-transform': 'scale(' + val + ')',
  'transform': 'scale(' + val + ')'
};

It’s important to set transform-origin, or the elements will be weirdly positioned on the page.

return {
  'transform-origin': '0 top',
  '-webkit-transform-origin': '0 top'
};

The style calculations are attached to the changes of window dimensions.

scope.getWindowDimensions = function () {
  return {
    'h': $window.innerHeight,
    'w': $window.innerWidth
  };
};
scope.$watch(scope.getWindowDimensions,
             function (newValue, oldValue) {
...
});

Few other things. My layout was sliced to the fixed width of 890px, that’s why I took 890 as the pivotal point of my scale ratio formula. You should take the default width of the layout as the base of your calculation.

if (newValue.w > 890) {
  return {};
} else {
  val = newValue.w/890;
  return {
    '-webkit-transform': 'scale(' + val + ')',
  }
});

With the directive in place it’s time to plug it in:

<script src="scripts/directives/tsResize.js"></script>
  <nav ng-style="topBarStyle()" ts-resize=""></nav>
  <div ng-style="mainContainerStyle()" ng-view="" ts-resize=""></div>

Be sure to use style “display:block” or “display:inline-block” and “position:relative” for all the inside components of the scaled elements with the default display. Otherwise they do not obey the scaling enforcement and grow way too long prompting a scrollbar.

<div id="main-container"><div id="inner-block" style="position:relative; display:inline-block"></div></div>

It all worked nicely and I was able to enjoy the smoothly resizing layout.

CSSConf US 2014 — Part One

2014-05-28T00:00:00+00:00

Geeks in Paradise

Today I was very lucky to once again attend CSSConf US here in Amelia Island, Florida. Nicole Sullivan and crew did an excellent job of organizing and curating a wide range of talks specifically geared toward CSS developers. Although I work daily on many aspects of the web stack, I feel like I’m one of the (seemingly) rare few who actually enjoy writing CSS so it was a real treat to spend the day with many like-minded folks.

Styleguide Driven Development

Nicole Sullivan started things off with her talk on Style Guide Driven Development (SGDD). She talked about the process and challenges she and the team at Pivotal Labs went through when they redesigned the Cloud Foundry Developer Console and how they overcame many of them with the SGDD approach. The idea behind SGDD is to catalog all of the reusable components used in a web project so developers use what’s already there rather than reinventing the wheel for each new feature. The components are displayed in the style guide next to examples of the view code and CSS which makes up each component. The benefits of this approach include enabling a short feedback loop for project managers and designers and encouraging developers who may not be CSS experts to follow the “blessed” path to build components that are consistent and cohesive with the design. In Nicole’s project they were also able to significantly reduce the amount of unused CSS and layouts once they had broken down the app into reusable components.

Hologram is an interesting tool to help with the creation of style guides which Nicole shared and is definitely worth checking out.

Sara Soueidan — Styling and Animating Scalable Vector Graphics with CSS

Sara talked to us about using SVG with CSS and included some really neat demos. Adobe Illustrator, Inkscape and Sketch 3 are the commonly used tools used to create SVG images. Once you have your SVG image you can use the SVG Editor by Peter Collingridge or SVGO (node.js based tool) to clean up and optimize the SVG code. After the cleanup and optimization you can replace the generic CSS class names from your SVG creation app with more semantic CSS class names.

There are a variety of ways to include SVG on a page and Sara went over the pros and cons of each. The method that seemed most interesting to me was to use an <object> tag which allowed for a fallback image for browsers that do not support SVG. Sara mapped out the subset of CSS selectors which can be used to target SVG elements, how to “responsify” SVGs and to animate SVG paths. Be sure to check out her slides from the talk.

Lea Verou — The Chroma Zone: Engineering Color on the Web

Lea’s talk was about color on the web. She detailed the history of how color has been handled up to this point, how it works today and some of the interesting color-related CSS features which are coming in the future. She demonstrated how each of the color spaces have a geographical representation (e.g. RGB can be represented as a cube and HSL as a double-cone) which I found neat. RGB is very unintuitive when it comes to choosing colors. HSL is much more intuitive but has some challenges of its own. The new and shiny CSS color features Lea talked about included:

filters
blending modes
CSS variables
gray()
color() including tint, shade and other adjusters
the #rgba and #rrggbbaa notation
hwb()
named hues and in hsl()

Some of these new features can be used already via libs like Bourbon and Myth. Check out the Chroma Zone: Engineering Color on the Web slides to learn more.

C$$

I will write up more of the talks soon but wanted to thank Jenn Schiffer for keeping us all laughing throughout the day in her role as MC and topping it off with a hilarious, satirical talk of her own. Thanks also to Alex and Adam for curating the music and looking after the sound.

Mobile Emulation in Chrome DevTools

2014-01-24T00:00:00+00:00

I have been doing some mobile development lately and wanted to share the new Mobile Emulation feature in Chrome Canary with y’all. Chrome Canary is a development build of Chrome which gets updated daily and gives you the chance to use the latest and greatest features in Chrome. I’ve been using it as my primary browser for the past year or so and it’s been fairly stable. What’s great is that you can run Chrome Canary side-by-side with the stable release version of Chrome. For the odd time I do have issues with stability etc., I can just use the latest stable Chrome and be on my way. If you need more convincing, Paul Irish’s Chrome Canary for Developers post might be helpful.

I should mention that Chrome Canary is only available for OS X and Windows at this point. I tested Dev channel Chromium on Ubuntu 13.10 this afternoon and the new mobile emulation stuff is not ready there yet. It should not be long though.

Mobile Emulation in Chrome Dev Tools

Once enabled, the Emulation panel shows up in the Dev Tools console drawer. It gives you the option of emulating a variety devices (many are listed in the drop-down) and you also have the ability to fine tuning the settings à la carte. If you choose to emulate the touchscreen interface the mouse cursor will change and operate like a touch interface. Shift+drag allows you to pinch and zoom. There are some cool features for debugging and inspecting touch events as well.

Learning More

If you would like to learn more, be sure to check out the Mobile emulation documentation at the Chrome DevTools docs site.

CSS Conf 2013 — When Bootstrap Attacks!

2013-06-03T00:00:00+00:00

I attended the inaugural CSS Conf last week at Amelia Island, Florida. The conference was organized by Nicole Sullivan, Brett Stimmerman, Jonathan Snook, and Paul Irish and put on with help from a host of volunteers. The talks were presented in a single track style on a wide range of CSS-related topics; there was something interesting for everyone working in this space. I really enjoyed the conference, learned lots and had great discussions with a variety of people hacking on interesting things with CSS. In the coming days I will be blogging about some of the talks I attended and sharing what I learned, so stay tuned!

When Bootstrap Attacks

Pamela Fox had the opening slot and spoke about the experiences and challenges she faced when upgrading Bootstrap to V2 in a large web app (Coursera). What she initially thought would be a quick project turned into a month-long “BOOTSTRAPV2ATHON”. Bootstrap styles were used throughout the project in dozens of PHP, CSS and JavaScript files. The fact that Bootstrap uses generic CSS class names like “alert”, “btn”, error etc made it very difficult to grep through the codebase for them. The Bootstrap classes were also used as hooks by the project’s JavaScript application code.

Lessons Learned

Fox offered some tips for developers facing a similar situation. The first of which was to prefix the Bootstrap CSS classes (e.g. .tbs-alert) in order to decouple Bootstrap from the customizations in your project. Some requests have been made to the Bootstrap team on this front but the issue has not been addressed yet. In the meantime, devs can add a task to their build step (e.g. Grunt, the asset pipeline in Rails etc) to automate the addition of prefixes to each of the CSS classes.

Another tip is to avoid using Bootstrap CSS classes directly. Instead, use the “extend” functionality in your preprocessor (Sass, Less, Stylus etc) of choice. For example:

  .ep-btn {
    @extend .btn
      &:hover {
          @extend .btn:hover
      }
  }

This way your project can extend the Bootstrap styles but keep your customizations separate and not closely coupled to the framework.

The same logic should also be applied to the JavaScript in your project. Rather than using the Bootstrap class names as hooks in your JavaScript code, use a prefix (e.g. js-btn) or use HTML5 data attributes. Separating the hooks used for CSS styles from those used in JavaScript is very helpful when upgrading or swapping out a client-side framework like Bootstrap.

Test All Of The Things

Pamela wrapped up the talk by explaining how testing front end code would ease the pain of upgrading a library next time. There are many testing libraries available today which address some of these concerns. She mentioned mocha, Chai, jsdom and Selenium which all look very helpful. In addition to testing front end code she offered up the idea of “diffing your front end” in a visual way. This concept was very interesting to someone who ensures designs are consistent across a wide array of browsers and devices on a daily basis.

Needle is a tool which allows you to do this automatically. Once you develop a test case, you can run Needle to view a visual diff of your CSS changes. I think this is an excellent idea. Pamela also noted that the combination of Firefox screenshots and Kaleidoscope could be used manually in much the same way.

Many thanks to Pamela for sharing this! The slides for this talk can be viewed here and the talk was recorded so the video will also be available sometime soon.

Honor your elders (and others)

2013-05-24T00:00:00+00:00

What an odd topic, you might be thinking. Some time ago, I began teaching my elders (who are rapidly becoming my contemporaries, curse you, Father Time) how to navigate the Internet. After almost two years of this, I’ve become more sensitized to seeing the ’Net from their POV.

Here’s a small fragment of a page I saw today (actual size):

The page numbers and arrowheads are the only navigation elements on this huge, complex page that allow you to move around the list of products. The numbers are an 11px font, and the arrowheads are 6px by 8px. For a senior citizen, or indeed anyone with less than perfect vision and eye-hand coordination, this is pretty challenging to find on the page, let alone use.

Here’s a quick challenge for you as web designer: try dimming your screen down a bit, to the point where it’s noticeably uncomfortable to use. Does your page still seem easy to navigate? Now try switching from your dominant hand to your other hand, and try clicking your page navigation elements (not just buttons, but drop-downs, menus, etc.). Still usable? If not, you may be designing your page to keep away some users. Just a thought.