Integration at the database

A conversation that continues to surprise me is the one that starts with “why don’t we just share the database”.  I feel that in the state of software development today that this is known to be a Bad Idea™ and we should try and avoid it first or if not avoid it, at least protect ourselves from the Bad Things That Can Happen.  The evidence in front of me is that this is not universally believed, so I will endeavour to capture my thinking here. Hopefully this will help us discuss what the trade-offs look like for the situation we’re talking about. Maybe at least have the same frame of reference.

This turned out to be long.   Let’s get started!

Why is database integration so appealing?

It is easy. The amount of effort to share your database with another application is trivial.  It is that simple.  One database connection string with authentication and we’re done.  Business value delivered.

Solutions like breaking up a monolith into multiple services, sharing data between two apps, 3rd party tooling that needs access to your data, or getting data to a data warehouse all could be sped up by sharing of your database as a quick solution to move forward.

This simplicity makes it very appealing.  What can go wrong?

Writing from multiple places is not fun

There are many patterns that try to help avoid updates from disparate places.  OO discourages direct updates through encapsulation – you cannot touch my data except through my interface.  In DDD you can use the aggregate pattern in order to help reason about changes to data which must all go through the Aggregate Root. The functional solution is to make everything immutable.  When using a pattern like Master Data – we’re trying to solve this problem by making an application / service the single source of truth.  All of these mechanisms are intended to help us reason about software. Software that writes to the database from multiple different codebases can be very hard to reason about.

Writing data from multiple applications violates the Don’t Repeat Yourself principle.  Knowledge about the tables, their defaults and their validations all need to be shared across multiple applications.  It is also hard for a developer to discover that a second application is writing to the table.  Doing a search in the repo they are working in will not find the access.  This can result in applications writing different defaults, validations, data types or not being aware of new columns or the meaning of new data.

A mitigation to this is to build a gem to share.  This is great until we do not keep all the applications on the same gem version and therefore we still have the same problems.  We need to lock step deploy every application using the gem to keep them in sync.  We now are building a distributed monolith.

What about read only – surely that is fine?

Maybe.

If you’re doing it to experiment and learn if something (like a 3rd party tool) is valuable, then definitely learn with direct integration.  After we’ve learnt, consider what the long term implementation is.  The pain that grows with this solution is in the long term maintenance and changeability of the solution, not the short term win.

For a long term solution, if you never change the database schema at all, then this is the quickest, easiest and – if you’re 100% right – most painless mechanism.  If you’re wrong, you’re probably in for pain.  How much pain depends on how rapidly things need to change and potentially how much the consumer is actually interested in.

The biggest problem is that we don’t know what will happen in the future, so assuming that we will never change the database in the future may always be a naïve choice.

What’s the big deal?

When you share your database you share your entire schema to be coupled to.  This is like exposing all of your data via an API where the API is every single SQL query that can be made.  Any change that is made to the schema can impact the consumer. If you give the entire schema that means you may need to ask permission for any change to your database schema as you do not know if the change you are making will impact the consumer.

The database schema is the API contract

Any shared API is a shared contract that the team owning the API guarantees to keep for all consumers.  When changing the API there needs to be negotiation and planning.  When we provide our DB to another team to consume, the entire database becomes the contract that we guarantee to maintain. And any changes to that contract must be negotiated.

Why is that bad?

If we need to ask permission to change something it will introduce friction.  We need to remember to talk to another team. We then need to actually talk to the other team.  Other teams have their own priorities.  Given the best will in the world, communication still takes non-zero time.  And it will need to happen for every single change we make.  This slows us down, particularly when we’re making a lot of changes.

Friction slows us down.  Can we solve that?

The friction around needing to ask permission can introduce several responses

  • We could start to work really, really hard to not change data in the DB
  • We could start to think really, really hard up front before we build anything
  • We could start to think about mechanisms that can reduce the number of things we need to communicate about.

The first two options introduce negative feedback cycles.  We spend more time in order to achieve them instead of less. And, given that things will change and we can’t know everything up front, we may make even more of a mess of the data when optimising for them.

Communication is important, so making sure the things that we’re communicating about are valuable is useful.  It keeps the signal to noise ratio high.  Starting to think of ways to reduce the number of things we are required to communicate about is useful, especially when that does not increase the time spent doing the new thing.  Ideally we should only communicate when the consumer must change.

Can’t we mitigate these problems?

We can introduce mitigations.

We can introduce rules – like adding columns is always allowed.  If we are allowed to add columns that is one change we don’t need to communicate about.  This is a net win as most likely the consumers would generally not notice additive changes. We need to jointly make this rule as it is plausible that consumers could notice and fail.

The consumer could document what they are using.  If we can find out what is being used, then we can self-serve.  The only catch is – what if it isn’t up to date. Humans are fallible so this may happen. This solution moves the work that was done by the publishing team in needing to communicate to the consuming team as they always need to document.  But we’re still doing that work.  A failure may result in a negative feedback cycle – be better! Document more!  Spend more time achieving something that will fail any time a human forgets.

Any mitigation that does not involve feedback from code / tests will potentially fail at some point.  If we can introduce automated mechanisms that tell us that we’re breaking something we could get ahead of that.  Automation does not forget.  If it is setup to run, it will run every time.  If we can get automated feedback, then we know that we’re impacting and can get ahead of the game.

Contract Tests

A good mitigation might be to come up with solutions similar to those for HTTP APIs – perhaps some of the contract testing ideas could help.  For contract tests, the consuming team writes tests that test the API how they use it.  The team exposing the API cannot change these tests.  Their system needs to keep them alive.  This is a great feedback cycle for exposed APIs.  And then the two teams can negotiate about how their usage can change.

The negative part about defining a contract on the base schema of a database is that it represents the base model that we’re trying to build and invest in.  This is where we’re experimenting and learning internally to the team and the system.  Having that coupled to an external consumer makes that experimentation harder

Is there a better way?

Could we define the contract explicitly?  Could we make it work like an HTTP API?  At that point potentially all the rules and expectations that we have around HTTP APIs come into play.

An option could be to populate tables or provide views that the consumer uses. The internal team does not use these tables or views but signs up to them being the API contract for the consumer. This means that we can now apply all the standard mitigations around APIs that we are exposing outside of our system.  This becomes a known space to work in.  This does not make it easy, but it does define the deliberate place where we can support the integration to our database while allowing us to retain control and freely refactor the rest of the database as we wish.

A key idea around refactoring is to build the simplest solution that we can safely refactor out of.  Coupling to a defined, contained interface as a contract feels like a solution that can enable safe refactoring of the underlying code design while keeping the defined contract working.

What does this solution lead to?

Suddenly we have reduced the scope of questions we need to ask when we change the database.  We now know we are fine if the change in the database does not relate to one of the contracted tables / views.  Suddenly a whole category of friction is removed. We can write tests to give us feedback when we are accidentally changing those tables or views.  We do not use them in our systems so we have no reason to change them unless we are changing them at the request of the consumer. Another radical idea would be to use the Dependency Inversion principle and allow the consumer to define what the data should look like.  It is for them after all.

This sounds like a lot of work.  Can’t we just use database refactoring techniques to solve this?

The mechanisms for database refactoring are awesome.  They make your database more fluid just like code refactoring makes your code more fluid.

When you own all of the code, code refactoring flows in small steps that allow you to incrementally deploy software over and over again.  It is an awesome engineering feat.

When you own all of the database, database refactoring allows changes to the database to happen in small steps that allow you to incrementally deploy changes across the software and database over and over again.  It is another awesome engineering feat

Code refactoring slows down and has friction when the edge of the code that you are refactoring is shared by another consumer.  For instance an HTTP API or a class exposed by a Ruby Gem. The steps to quickly change the system run into friction around communication, planning and the potential that you might need to wait a long time before you can finally remove the interim code that is helping make the progression from one form of system to another

Database refactoring slows down and has friction when the database that you are refactoring is shared by another consumer.  The steps to quickly change the system run into friction around communication, planning and the potential that you might need to wait a long time before you can finally remove the interim code that is helping make the progression from one database design to another.

Database refactoring is really useful for helping understand how to change a legacy database shared by another consumer out of your control.  It moves it from static and scary to change, to slow moving and more malleable.

Database refactoring is really useful for helping speed up your changes in data when you own the whole stack.  It allows you to incrementally change the whole system in a far more fluid way.

Database refactoring doesn’t solve the communication and waiting overheads that come with co-ordinating with other consumers.  You can only clean up your refactoring as fast as the consumer follows your changes.  You still need to communicate about every change in case it has impact or introduce mitigations for that as described so far.

Is not sharing the database an option?

The first prize would be to not share the database at all.  If we do that we remove a category of conversation and design problem that we no longer need to think about.  If we don’t take a dependency, we don’t have to deal with it.

But one must assume that the sharing of data is necessary, otherwise we would not be contemplating that in the first place.  In which case we need to be able to build something to provide that. Whether it is an API to be called; or we write data to another database and that is the contract; or we event it and other code reads it and makes it available in another database and that is the contract.  It is inevitable that something needs to write the data somewhere for the other application that wants it to gain access.  It will depend on what that application is as to what makes most sense. But something will need to be built to provide the data.

Another problem… data is not always meaningful without code

The data in an application’s database might need code to make it mean something to the business domain.  Keeping this in sync across multiple applications accessing the database directly can also lead to pain and violates DRY.  Deliberately providing data that has meaning is far more useful – whether that is directly into a database tables where that interpretation is potentially set or published out in an API that uses the code to do the interpretation.

Some practical history and burnt fingers

I have learnt this lesson painfully in the past.  The clearest example is an application which was exposing a new API to replace an old one in a large monolithic app.  The desire was to build a model that better represented the domain. The implementer was going to build it in a new rails app.  It would be the new API and it would represent a better view of the system. At the same time, it was viewed that this API would not change after it was released.  So when reviewing and conversing about the solution and how it would be maintained, the fateful “it is not going to change, so lets move forward and not worry about maintainability now” was stated.

The decision in this instance conversed around sharing the model as a Gem between the two apps, or otherwise sharing it as views and having the new model consume the views.  Having a model as a Gem for a concrete implementation of data is not a great idea as it means that all consumers must always have the latest gem deployed as that is the latest representation of the DB and hence any time a DB change happens all consumers containing the gem should be redeployed – even if the change has no bearing on a given consumer, they need to keep in sync.

In this instance we chose to share views to share the data.  We chose to make the primary app own the DB schema – as otherwise we had multiple apps owning the DB schema and we could get into trouble managing changes to the DB.  But that meant any view change required for the new API needed to happen in the primary app first.  It would also need to be deployed to live before the API code could consume it.

If you recall the “its not going to change” comment.  It turned out six months later that we thought this API was useful and started to use it – both directly and from a search service.  Long story short, we did change the data a lot and this design choice became a real pain.  Changes only needed in data for the API caused multiple repos to change and be deployed.  Deploy could be painful as sometimes the different database schemas were out of sync. Deploying an older version would downgrade the views for the API consuming it.  Testing could be painful as we needed a matching test database based on the main application so that the views were up to date.  There were lots of lots of little niggles due to the coupling of the implementation.

The worst part of this choice was when people moved into the project they struggled to understand the couple.  They would forget the process as too many things were solved by “we should remember to do XX”.  The solutions were too often human’s being better, not systems providing feedback when the humans inevitably did the wrong thing.  But it is hard to provide automated feedback about changing code in one repository that is affecting another one.

When we did this I was working with the best bunch of agile software developers I have worked with.  It still caused us a lot of pain and we owned all parts of code accessing the database.

Change is inevitable, how fast you embrace it is up to you.

I work in fluid environments that accept that code will change.  I accept that we don’t know everything.  We will change the systems we build as new knowledge and designs emerge.  Any team that needs to co-ordinate with another team to ask permission to make a change slows down.  There will be friction in refactoring at the shared edge of our systems.  I prefer to live in hope that we will be able to make more and more changes, to experiment and innovate with new products and ideas simply because we choose not to embrace solutions that will slow us down. Solutions that continue to be reoccurring work aren’t great.  Solutions that stop us from having to do a certain category of work speed us up. Work not done is time available to do other useful work.

Prizes… or is that prices?

First prize – don’t integrate at the database.  If we do not do it, we do not need to read this entire complex post that touches on many nuances and implications of doing this.  And inevitably there are more subtleties I haven’t even touched on. If we don’t do it, we don’t have to think about what it means to do it.

Second prize – integrate at the database with a completely static data schema. This is probably both unlikely and not necessarily very useful for a company that is driving innovation.  But that is the only time that integrating blindly is not going to cause pain.

Third prize – integrate but do not give up control or give up as little control as possible. Look to how you can reduce friction as much as possible without generating repetitive work and especially without creating work that humans need to remember to do or that require us to simply “be more better”.  This is beneficial for both the data owner and consumers in the long run.

I default to first prize and hang on to it for as long as I can.

Advertisements

Know where you’re going

A core idea in agile software development is that we don’t know enough right now so we should only build enough for what we actually do know right now.  This is sensible.  This idea underpins evolutionary / emergent / test driven design – allowing them to thrive.  If we can safely and confidently change the system in any direction from where it is now, then we are in a good place.  We are keeping the XP cost of change curve as flat as possible.

But the cost of change may become high if we need to continuously rework everything. If the knowledge is available to help make more informed design choices earlier, we should use it.

Know where the code is going

Good software developers are intentionally trying to make the code base better.  This is highly desirable.  Good software developers will refactor confidently and allow new designs to emerge.  When you have 6 good developers refactoring the same code base into what in their minds is the best solution it is plausible that you may land up with 6 very different designs going in 6 very different directions.  This might not be ideal.

What would make those 6 good developers into a great team is a shared understanding of how the code is being refactored so that we don’t land up with 6 different designs, but rather one collaborative design that everyone has contributed to – pulling it in the same general direction.

As a team, discussing about where we’re refactoring the code to is important.  A given pair might not reach the best design while working in this sprint and another pair may augment and grow that design in the next sprint.  If we share where we’re going, we can hopefully get somewhere in the region of the shared destination.  And we can more meaningfully converse about changes in design as the requirements change and agree on the next destination.

But don’t inhibit innovation and new ideas

The counter to this is that if a good developer is building something and they choose to build something different to the current design – maybe it is simpler, better, cleaner – this should not be inhibited.  Do not strive for uniformity and accidentally crush the very innovation that you need to channel from a good developer in order to have a great team.

Know where the business is going

A common way of breaking up stories is around the CRUD screens / actions.  It is sometimes easy for a Product Owner to define a series of screens that allow them to administrate some set of information. It is plausible that these screens are built without a conversation of why the screens are being built.  Possibly this is because the PO doesn’t yet know the exact details on how these things are going to interact.  But if this is the case, it is plausible that when the PO finally specifies how these CRUD things are going to interact in a meaningful way that the team could turn around and suggest that, based on how those screens have been built, that isn’t possible – or at least it is very hacky and we’re already building a legacy system with bad design.

Knowing something about where the business is going in the next sprint or 3 is useful.  Use it to track how the design is evolving and hopefully take this at least somewhat into account when designing the code.

But don’t future proof too soon

Don’t worry too much about planning for future needs that are trivial to add in a future sprint.  We don’t need to future proof the design.  We only need to know where it might go so that we can perhaps go there more easily later.  We need to know that the short/medium term goals will be supportable by the design we are creating today.  If it isn’t, it doesn’t matter too much, but the cost of change will probably go up if we need to massively refactor the entire system every sprint – so what can we do to help avoid that?

Know where the architecture is going

Systems are continuously evolving.  As architectural issues arise, an idea of what should be done to solve them should be discussed.  If we can agree on the direction that we need to move the overall architecture and understand what it could look like, then any team may be able to start building that within existing work that they have, in an opportunistic way.  If we have no clue where we would like to go then any team will probably continue to do exactly what they are doing now.

Alternatively, any team may start to innovate in different directions and again we may land up with the architecture of the system being pulling in several different disparate directions which may not be a beneficial in the long run.

If your teams discuss and plan what the architectural changes could look like, then we know where we’re going and we can start working out the baby steps to get there.  Those baby steps may be started to be done inside current work.  But without any clue of where we going we can’t even start to take any baby steps.

But don’t be too constraining

Architecturally knowing where you’re going is important – but the micro details shouldn’t be constrained.  It shouldn’t matter if we use redis or memcache in terms of an architectural solution.  Let the teams converse and decide as a group on the actual solution details when they are needing the solution and allow that to be based on the real experience and constraints they are being experienced in their teams.

Know sort of where you’re going

The precise destination isn’t important – the general one is. The details will vary.  The overview of the destination over the next 2-3 months hopefully will grow and evolve.  Despite that, hopefully it will still be comparable enough to call reasonably the same.

How abstract the destination is depends on the need.  For instance, it might be useful to sketch out the boundaries of several micro-services to have some idea of the destination and to give teams an idea of what they could break out of a larger system.  But don’t be married to those decisions if they turn out to be incorrect.

Use the knowledge just in time

Knowing the destination today should inform the code as a potential destination to refactor towards.  We shouldn’t be focusing solely on the road directly in front of our feet.  We should be looking up into the horizon and gleaning any knowledge we can of what is up ahead.

Knowing where we are going will allow the whole team to pull the code and system in a similar direction.

Knowing sort of where we are going should lead to an informed just in time decision about when to do something with that knowledge.

DDD, Aggregates and designing for change

I have been introducing several domain driven design patterns to the teams that I work with over the last while.  In doing so I have been struck by the repetition of a core principle for many of the DDD patterns.

An example – the aggregate pattern
The aggregate pattern focuses on the business domain, attempting to answer the desire for a software developer to work with fully formed domain objects that interact with each other in a meaningful way.

The aggregate pattern defines the aggregate as a combination of objects that interact as a single unit.  The aggregate is only interacted with via the root of the aggregate.  This ensures that the aggregate root can maintain the integrity of the whole aggregate.

If all interactions with the aggregate are via the root aggregate this means that we can control the implementation of the aggregate behind the interface of the root aggregate.  The aggregate should be designed as a cohesive unit and is decoupled from the rest of the system via the aggregate root’s interface.  The aggregate root’s interface is the API to the aggregate.

Tensions
The complexity is in keeping the aggregate small while useful.  Tension exists when the aggregate gets bigger. The aggregate interface can become complex due to the constraint that all access must occur through the root aggregate.  This tension may push one towards designing smaller interoperable aggregates rather than allowing a large ball of mud to be formed.

Unidirectional?
Just as a design choice could be to have unidirectional models; it may also be an interesting design choice to build an aggregate with unidirectional models – with the root aggregate being the model that knows about (potentially) all the child models.  This may be useful.

My personal preference is to try to keep things unidirectional for as long as it is sensible, but as soon as it isn’t sensible allow connections in both directions.  The aggregate root is controlling the access to the objects in the aggregate.  Allowing objects in the aggregate to know about each other bi-directionally increases the complexity of the aggregate as a whole but, assuming a reasonably small aggregate, the principle of small contained messes is still supported behind the interface exposed by the aggregate root.

The core
Circling back to the core principle for many of the DDD patterns – the factory pattern, the repository pattern and the aggregate pattern all define mechanisms for creating a well-defined interface and hiding the implementation details behind the interface.

The factory pattern provides a creational interface to build an object.  We get well formed objects from it and don’t need to know how they were formed.

The repository pattern provides an interface that abstracts away object storage / query.  We ask it a question and get objects back.  We tell it to persist something, and it happens.  We do not need to worry how.

The root aggregate in the aggregate pattern provides an interface that abstracts away the implementation of the aggregate.

These patterns make code simpler and reduce complexity by clearly defining what should go behind the interface and what should not.  These patterns allow the caller to not worry about the implementation details behind the interface.  All of these patterns support the idea of smaller messes.  If the implementation behind the interface is a little messy, it doesn’t matter, as long as it can be refactored safely later and the caller is not influenced at all.

Decouple the interface that the outside world uses from the implementation underneath.  And know why the code is placed behind the interface.  Design a cohesive unit behind the interface.  This is also how TDD encourages code to be written, assuming you can design the interface well.

In practice
When discussing domain driven design versus other design ideas and using test driven design to build software, there are often questions around which pattern to use or how they should interact.  These questions are often attempting to get black and white answers to a complex contextual problem that probably has many shades of grey in it.

What has struck me most about introducing DDD after introducing TDD and emergent / evolutionary design is that the core principle is to contain the messes behind the interfaces.  Have good interfaces and decouple them.  And ensure the implementation behind the interface is cohesive and can change freely as needed.  That is the core of software design and most patterns.  How do I change later?  How do I keep in control of the code so that when change comes (and it will come! Especially in unexpected ways) it is not accidentally impactful on the rest of the system.

Focus on embracing change
Worry less about the patterns, than what the patterns are trying to teach you.  Use the patterns, understand them, they are a language that can be used effectively among developers.  But the patterns are not the end game, the changeable system that they encourage is.

Keeping it Simple – unidirectional models

Keeping code simple is an art.  It may require a reasonable amount of work – refactoring and trying design experiments to keep it as simple as possible.  Changes to requirements may result in the current design no longer being the simplest thing any more.

One way to attempt to keep things simple is to reduce complexity by not implementing anything that a current use case does not need.  That way, changing the design only has to worry about code that is being used – there is no guessing game.

Another way to attempt to keep things simple is to reduce the paths that can be taken through your code base to reach a given point.  Making small cohesive units that can be reasoned about with a well-defined interface to the rest of the code base ensures you can change those cohesive units more easily.

Adding complexity

A way to increase complexity is adding unnecessary code.  This is often done because “it’s obvious that it is the right thing to do” or “we’ll probably need it” rather than driven from any actual use case.

An example of this can often be seen when using an ORM.  Given a model that is composed of attributes and a list of another type of model, a common pattern is for both sides to know about each other.  The parent model will have a list of children and the child model has a reference back to the parent model.  This is particularly obvious when the design is data driven (driven from the database tables) and the designer feels comfortable just grabbing any table / model and loading something from it and working from that view of the data.

A classic modelling example is an implementation of an Order.  An Order may have many Line Items in a list.  In the standard way that typical ORMs encourage you, the Order model will know about its Line Items and a Line Item will know about its Order.  This means that I can load an Order object and expect to be able to access its Line Items.  It also means that I can load an individual Line Item and directly access its Order.  And then I could use that Order to get the Line Items, one of which was the original object that started the request.

What’s wrong with that?

In the simplest implementation with limited complexity this may be fine.  But it could lead to some problems as the complexity of the solution grows.

Cyclic dependencies

One problem that can arise is cyclic dependencies – where the parent can call a child and the child can then call the parent and around we go.  This may be hard to reason about – particularly as the object graph grows in size.

Maintaining a cohesive world

These convenience methods increase complexity.  Having a design that can be entered from anywhere and needs to remain cohesive in any direction from that entry point increases complexity.  Additional code may be written to compensate.

It can lead to needing the world to be cohesive no matter which object I load and manipulate.  By allowing the Order to know about the Line Item and the Line Item to know about the Order, allows the option to add a Line Item separate from an Order, which may not be valid in the domain.  We may always expect a Line Item to have an Order and this could be violated.  In order to resolve this, we need to add validation on the Line Item to ensure there is an Order.

A potential design may be that changes to a Line Item may expect changes on the Order model.  If we can load the Line Item first, then we need to solve the consistency of the Order model.  Clearly we should add callbacks when the Line Item model saves in order to ensure the Order is up to date.

Maybe we have a tax amount stored on the Order.  When this updates, all Line Item’s need their totals to be updated due to the change in the tax percentage.  Clearly we should add callbacks when the Order saves to update this.

If I can access a Line Item directly, I can also change its total.  This may require the Order’s total to be updated.  Clearly we should add callbacks to update the Order when the Line Item is saved.

Now I’ve written a bunch of callbacks in order to keep my domain valid because I can load anything and use it.  I also may have introduced a cyclic dependency and a cascade of DB updates that I don’t control very well.  When I save the Order, all Line Items will be loaded and saved.  Each Line Item may change the total value in the Order… and if we do this badly we’ll get stuck in an unexpected loop.

Increased testing for unsupported use cases

In an ideal world, every use case that you build should have a test.  Putting in the back connections between two models should be driven by that use case.  If you don’t have a failing test case, don’t write the code.  If you don’t have a use for the code… don’t write the code.  But if you’re writing the code, write the test.  Which increases the testing burden – for unsupported use cases.

Containing complexity

Instead of providing inconvenient convenience methods, why not contain the complexity and not provide it?

Unidirectional linkages

For a start, could we make all models talk in only one direction?  What would that do to the code?  Suddenly we have reduced complexity.  In order to load one model, it can only be accessed one way.  There is no expectation of the other way.

For instance, assume that the Order knows about its Line Items.  But the Line Item does not have a back reference to the Order.  What would that mean?

A Line Item can never be created without an Order.

A Line Item is updated through the Order, therefore any consistency that the Order needs to maintain due to changes in the Line Item are simply done in the Order.

When the Order’s tax is updated, we now have a design decision – do we update all Line Items at Order save time?  Or do we update Line Items as we pass them out of the Order?  Suddenly we have control over the performance characteristics of this update.

The Order / Line Item relationship is now easier to maintain and reason about as the expectations of the relationship are simpler.

Line Items may still be read directly, but the design states that there is no expectation of accessing the Order.  In order to access the Order, use the order_id that may be in the Line Item object to directly load the Order and get a fresh object.

But that is more work!

Suddenly we have a little more work.  The little more work is clear and obvious.  We can’t load a Line Item and expect it to just get the Order.

I would argue that the backlinks have similar (and potentially significantly more) complexity – but that isn’t visible until later when you realise that the Order needs updating when you save the Line Item that you loaded directly.

Not putting in the back links acknowledges the real work to be done and the thinking required instead of pretending it isn’t there.

Let’s go further – the Aggregate Pattern

What would happen if we defined a model like the Order / Line Item relationship, but only allow any interaction to the Order / Line Item cohesive unit via the Order?  What would happen if when we interact with the model, it was always fully loaded and well defined and hence our expectations would be well defined.

This is the aggregate pattern, a pattern popularised by domain driven design.  The Order model would be the root of the aggregate. A Line Item would not be accessible to the domain except via the Order.  A design choice could be to only allow new Line Items being created via the Order.  Suddenly we have control of all interactions with the models.

There is more to the aggregate pattern and there are more implications and ideas, but I’ll write on that another time.

Keep it simple

Why not try to keep things simple instead of assuming things are necessary?  Experiment with patterns that have “extreme” ideas, as maybe there is something to learn.  Choosing constraints in your design that help simplicity and reasoning – even when it means slightly more explicit coding – can be a liberating thing.

Maintain your confidence in the face of change.  Keep it simple.

 

A potential caveat

Maybe your ORM needs the backlinks to do some of its magic.  If that is the case, it feels like it might be unexpected.

Discoverability – a design choice

I recently blogged on discoverability being a naming choice. I talked about how the choice of name may make changing it later easier or harder.  What would happen if we start using the qualities of dynamic ruby to do some meta programming – how would that influence a future developer’s capability to discover how the code works?  How does this break the model of “Find in Files” discussed in that post.

Let’s start by making it worse

Imagine an Active Record model, Tour, with a column full_price_for_tour in the DB.  In a vanilla rails project, searching for full_price_for_tour in the codebase may result in no hits at all.  Equivalently, with looking at a caller that calls full_price_for_tour on an instance of Tour, we will not find any reference to full_price_for_tour in the class file for Tour.  For new Rails developers this can be very confusing.

The programming model that the active record implementation is helping us with is potentially a useful one – dynamically determining the methods from the database and creating them on the object.  But it is harming discovery of how the code works.

So how do we help developers discover where the code is?

In a Rails codebase the annotate gem comes to the rescue.  It annotates the model classes based on what is in the DB for the matching table.  This allows a developer to discover the list of dynamically created methods that they can call on the model object – and hence what data the model object does expose.  This is a Good Thing.

Searching for full_price_for_tour will have a match in the Tour class file – as a comment in the annotations.  The developer now knows this method is the column in the DB as the annotations are allowing that discovery.

And then someone gets clever

The Active Record implementation leverages the dynamic qualities of Ruby to do something useful for developers.  All dynamic meta programming may not always be beneficial.  There are always trade-offs in software design.

Some production ruby code I saw recently implemented something along the lines of:

  def self.method_missing(method_sym, *arguments, &block)
    @hash_obj[method_sym]
  end

This code was written to provide helpers to access a hash’s properties with method calls.  This was a convenience method.  And there were some other helper methods defined in this class in order to work out some standard answers to questions that the hash provided.  On the face of it, this looks like a clever use of ruby as a dynamic language.

But how does another developer discover all the methods that this class responds to?  We need to find the hash definition to discover that.  In this case, the hash was from some json from a HTTP POST.  The simple question of what can we expect this object to answer to was not codified in the code at all leaving all developers on the team very unsure what the correct method names were.

Going back to the refactoring example.  When, assuming this was the Tour class and we were calling full_price_for_tour on this object – how would we find out what the implementation was?  First we’d fail to discover one with a “Find in files” type search.  Then we would have start spending some time working out why there wasn’t one and what the magic was that made it work.  As a developer this is time wasted.  Even worse, when the question is “what is the full interface”.

Another clever thing

Some ruby code I can easily imagine is:

  def self.method_missing(method_sym, *arguments, &block)
    method_as_string = method_sym.to_s
    split_methods = method_as_string.split(‘_’)
    obj_to_call = split_methods.shift
    method_to_call = split_methods.join(‘_’)
    obj = self.public_send(object_to_call)
    obj.public_send(method_to_call)
  end

Assuming this code is in the Tour class, we now can call fullprice_for_tour* on the Tour class.  This will then get the fullprice object inside this instance and call the for_tour method on it.

tour.fullprice_for_tour would be the same as tour.fullprice.for_tour.

* I’ve changed the method name to fullprice in order to make the code example simpler.

This kind of code is clever.  But it stymies discoverability again.  When I search for the method fullprice_for_tour I will be unable to find any definition of it anywhere.  I now need to investigate the Tour class file in order to determine that there is a method_missing handler, and work out that actually we are calling fullprice on that class and for_tour on the FullPrice class.  Now I can find the code.

The simple model of searching for the implementation is broken by this coding style.  Searching now becomes an iterative process when nothing comes up.  Which takes longer.

And then there are Rails delegates

In Rails you can add to the Tour class

  delegate :for_tour, to: :full_price

which enables

  tour.for_tour

to be the same as tour.full_price.for_tour

You can even add prefixes

  delegate :for_tour, to: :full_price, prefix: :full_price

which now enables

  tour.full_price_for_tour

to call tour.full_price.for_tour

This saves a developer from writing

  def full_price_for_tour
    full_price.for_tour
  end

in the Tour class.

We save writing a method definition.  But the discoverability is hurt – particularly when the prefix is used.  We now have to do multiple different types of searches in order to discover where full_price_for_tour is defined.  And we need to remember to do that.  And as determined, there could be multiple different ways in which the method could be defined dynamically.

A Hypothesis

The cost of discovery should be at least N times lower than the cost to write the code.  Where N is the total number of times the code is to be viewed and understood up until it is deleted.

I would hypothesise that the benefit of not having to write a trivial method definition makes the discoverability of the method take at least twice as long.  In general my first guess will be wrong.  I have to guess at least once more – looking for delegates.  But then again, it might be another dynamic way, so I might need to keep on guessing.

The design choice of coding this way results in a codebase that on average takes longer to discover things in.  Which means over time, software will take longer and longer to be delivered.  As compared to the constant cost at the time of typing a little more.

The constant cost of typing the method definition occurs once – when the developer writes it.  The cost of discovery occurs every time a developer needs to understand where the code is defined or from where it is called.

So is dynamic meta programming ever justified?

For the majority of developers, the core type of work is business applications that mostly do CRUD operations.  Use cases are driven by actual requirements.  Actual requirements are concretely defined.  They should have concrete tests that define them.  Using dynamic meta programming is almost never required.

Sometimes the code is doing the same thing behind those concrete interfaces.  The code may want to be refactored to take advantage of dynamic techniques to reduce duplication and expose a new level of abstraction.  This can be valuable when things are in fact the same.  If the abstraction makes the system easier to change, this is good.  But these changes should be done beneath the concrete definitions of what the system does.  The system is a set of concrete interfaces and use cases that have concrete tests.  That is what allows us to refactor to a more abstract design below the covers.  As the underlying code becomes more abstract, the external interface and the tests calling the interface remain specific.  The abstraction should not be the exposed interface of your average business application.  The abstraction should not make it harder to discover how the system works.

Observations

Many developers value locally optimizing the time that they save writing code.   At the same time, they ignore the amount of time they cause someone else to waste when attempting to work out the implementation at a later date. Most code is write once, read many.  Optimising for discoverability and understanding is more useful on your average business application than optimizing for the speed at which you can take on the next story.  Optimising for speed to the next story now will result in slowing down later due to spending time discovering how to change the code in order to implement the new story.

I value discoverability.  Having worked on many large code bases – finding stuff needs to be as easy as possible.  I understand others may value terseness more.  Design is always a trade-off.  Understanding what is being traded-off is important.  I don’t consider using meta programming, to reduce lines of code that I need to write, more important than being able to discover and understand that code quickly and reliably later.

If your team uses code like the Rails delegate everywhere in their code – then everyone already knows that all searches to discover a method’s usage or implementation should take that into account. Everyone will be doing it and perhaps that is fine – despite increasing the complexity of that search.  The importance here is consistency and providing an element of least surprise.

If a codebase sometimes uses magic – method_missing, delegates, etc – and sometimes does not, then it becomes more of a guessing game when to search for them and when not to.  That is a real cost to maintaining a codebase.

If I haven’t found the code in my search – is that because it isn’t there or is it because it is using some other magical way in order to be declared?

Don’t use dynamic meta programming unless it is really useful.  Most things are cleaner, clearer and easier to change without meta programming.

If you’re breaking the paradigm, use something else to mitigate the loss.  In the case of Active Record, using the annotate gem to help discoverability mitigates the dynamic implementation that makes discovery of the methods harder.

Think!

Think about discoverability.  Think about the cost of making discoverability harder.  Is there something that can be done to mitigate the cost of this design choice?

All design choices are choices.  Weigh up the pros and cons for yourself and with your team.  Discoverability is just one facet of a good code design, but all too often it isn’t even a factor in the thought process.

Discoverability – A naming choice

When reading or refactoring code, it is important to be able to easily find all callers of a method or to go to the implementation of a method.  In static languages, IDEs make this reasonably easy.  However, if reflection is being used, they may still fail us.  It is simply easier to parse a static language to know the types involved and find the right ones to tell us about.  In dynamic languages that is much harder.

In a dynamic language, a key way to find all references to an object’s method call is “Find in Files”.  This means what we choose to name things may make it harder or easier to change later.  It may also make it harder to discover who is calling the method – or even that the method exists.

A unique name

In order to refactor a uniquely named method on a class

  • search for the method name as a string
  • rename

As we know it is unique, this will work.  In fact, you might be able to run a simple find and replace in files instead of looking at each result individually.

This scenario however is unlikely.  At least it is unlikely that we emphatically know that a given method name is unique.

A more likely scenario

In order to refactor a descriptively named method such as full_price_for_tour on a Tour class

  • search for the method name as a string
  • in each search result – check all references to the method name to see if they are in fact using a Tour object
  • if this is a Tour object call, rename the method call to the new name.

This is more work as we need to look at each result.  Hopefully with a descriptively named method the number of usages will not be too high.  Even if the number of usages is high, hopefully all usages of the name will in fact be on the Tour class.

However, we do need to look at each result as this process is potentially error prone.  There could be other method definitions using the same name that we need to NOT rename.  Hopefully there are tests that will tell us if we fail.  And hopefully the number of callers to change isn’t too high due to the descriptiveness of the method so the changes to the callers is clear.

Sometimes the results are less simple

Now imagine repeating the above exercise, but now the name of the method to refactor is name.  Suddenly we may have a huge number of hits with many classes exposing a name method for their instances.  Now the ratio of search result hits that are to be updated is no longer almost 100%.  The probability of error is much higher – the greater the number of hits, the more actual choices that need to be made.

An IDE may help

Immediately the IDE lovers will point out that, using an IDE is the solution.  And yes, it could help.  But IDEs for dynamic languages are generally slow and CPU/memory intensive as the problem is a hard one to solve.  And they won’t always be correct.  So you will still need to employ strategies using a human mind.

Naming things more explicitly can help

A more useful model – even if you’re using an IDE – is to name things descriptively, without being silly.  Things like tour_name and operator_name instead of name may help someone discover where / how a method is being used more easily.

Designing code to only expose a given interface can help

Building cohesive units of code that only interact through a well defined interface makes changing behind the interface a lot easier.  However it still doesn’t discount developers reaching in behind the curtain and using internals that they should not.  So you will still need to check.  Hopefully code that breaks the design like this will be caught before it gets merged into the mainline, but you never truly know without looking.

Reducing scope where possible can help

Knowing the scope of access of the thing you need to change can make changing it easier as it reduces the area you need to look in.  For example, if something is a private method then we know that as long as all usages in this class are updated, then we are completely free to change it. Unless someone has done a private_send from somewhere else…  Or we are mixing in a module that uses the private method from there… Both of which I’d like to think no one would be that silly to do.

Testing can help

Obviously having a comprehensive test suite that calls all implemented permutations of the usage of the method will help to validate a change.  It will hopefully help us discover when we have missed updating callers.  Or when we’ve accidentally changed a caller that shouldn’t be changed.  However if there are name clashes for the new name, it is plausible that it might not give you the feedback that we expect so it isn’t a silver bullet if you aren’t naming things well.

Think! 

Think about naming.  Think about discoverability.  Is there something that will make changing this easier in the future?

Think about the cost of making discoverability harder.  Be aware of the implications of a naming choice.  Is there something that can be done to make it easier to safely refactor away from this choice later?

Can we make things worse? Discoverability is a design choice to make easier or harder.

Discovery – a HTML and JavaScript example

I value ease of understanding in code. I find it helps me to develop more maintainable software that I am confident to change. One of the things that I attempt to optimise is how easy it is to discover how the code works. I ran into an example of this is in a code review recently that I thought was worth sharing. Below is a modified example of what I was reviewing.

The example

Assume the following HTML.

  
  <textarea name=’area1’ id=’area1’ class=’area-class’></textarea>
  <textarea name=’area2’ id=’area2’ class=’area-class’></textarea>
  <textarea name=’area3’ id=’area3’ class=’area-class’></textarea>
  

Along with the following JavaScript in a .js file that is loaded with the HTML page.

  
  function update_counter() {
    // some code to update the element
  }

  $(“#area1”).change( update_counter );
  $(“#area2”).change( update_counter );
  $(“#area3”).change( update_counter );
  

How does the next developer know that there is a counter being hooked up? How does the next developer know how it is being hooked up? How easily could a developer look at the HTML and successfully add a new textarea with the same capabilities?

Based on the above HTML alone, there is no clue that there is a JavaScript hook into it. There may be a JavaScript include in the HTML page that will lead us to the file that is doing the work, but that isn’t something that will be looked at unless there is a reason to look and the HTML isn’t giving a reason to look.

Knowing which file to look at could be even less obvious if you’re using something like the Rails asset pipeline that precompiles and bundles files together as there is unlikely to be a single include for the .js file.

If we knew we were looking for some JavaScript, another discoverability mechanism would be to search for any instance of the textarea’s id or class being used in JavaScript. This could be a little painful.

A simple fix

In this case, a simple fix is to move the initialiser that hooks the update_counter to the specific DOM elements to be coded on the HTML page itself. This highlights to a developer what DOM elements are being bound to JavaScript in the same file as the elements are being defined. This provides a breadcrumb for the developer to follow in order to discover how things are hooked up.

When I have used KnockOut.js in the past, I have had the binding action run on the HTML page to bind the HTML to the relevant JavaScript model to help allow discovery of what JavaScript code to look for.

What if it isn’t that simple

What if the code that is being run to do the binding is a lot more complex?

Another way to do this could be with data- attributes.

  
  <textarea data-counter name=’area1’ id=’area1’ class=’area-class’></textarea>
  <textarea data-counter name=’area2’ id=’area2’ class=’area-class’></textarea>
  <textarea data-counter name=’area3’ id=’area3’ class=’area-class’></textarea>
  

and the Javascript binding becomes

  
  $(“[data-counter]”).change( update_counter );
  

This code now allows the developer to look at the mark up and ask the question “What does the data-counter attribute do?” This will lead them to the fact that there is JavaScript binding to the element.

Even if the developer does not take any notice of the data-counter attribute, copying a row and updating the id to a unique area id and name will still work the same as all the other textareas without the developer needing to think.

The term “Falling into the Pit of Success” is sometimes used to represent things that developers will do by default that will in fact be the correct decision. This is an example of that.

The additional benefit is that the data-counter could be used on multiple pages across the site and it will work the same.

The actual instance

In this case, the counter is visually obvious, so there are some clues for the developer to try to look for the JavaScript counter and how it ties in. However the actual instance that I was code reviewing was saving something to local storage per textarea, and then putting it back, in order to implement a feature. This was even more opaque as it was less obvious it was happening or why.

Value discoverability

Always think about how the next person will discover how the code you are writing now fits together. It might even be you in 6 months time. How quickly can it be worked out? Is it explicit and obvious and easy to do the right thing? How will they discover what you did?

The faster it is to discover the way the code works, the less time will be wasted trying to find it out how it works and the more effective you and your team can be.