Definition

Those are my own definitions, that i know intuitively:

• If you have a service: any change that can break a client implementation without him changing anything.

• In a library or code: any API or behavior change that will force users of the API to change their code in order to continue using a new version.

You can find more dictionary like definition on Wiktionary

Identification

I identifying a breaking change is hard on developers since it force us to wear the hat of the user who uses our code.

Good testing culture, one that force creating unit tests (TDD anyone?) and UI automation tests helps in that regard. Makes it easier on the developer see the other direction, simply since he supposed to see it as part of his day to day job.

But even in the world of code to code APIs - breaking changes slip through unidentified simply since the language customers use and that used by the developers is usually not the same language.

In the world of on-line services and UI things are a lot worse.

Why do it?

Breaking changes to API is like refactoring to implementation.

If you do it in the correct amount, at the correct time, it helps your code grow.

If you do it at the wrong places, you end up costing to much to your customers that they will start abandoning your code/service and move on to other greener libraries/services.

Breaking changes can be forced on you for security reasons, design flows that needs to be corrected, unintuitive API/behavior that makes it harder than necessary to use your code/service.

They can be done as part of a new design or new vision. And they have the potential of opening new uses for your code that were closed before.

The right way

As with anything there is no one right way, but there are guideline:

• Since customers are paying the price, you need to notify them as early as possible, help them prepare.

• Always assume that there is a customer that will be hurt from that change, so try and identify them before hand and fix it with them in advance.

• If you can support multiple versions (using multiple/versioned APIs, or package management or any other means) do it and leave the old versions functional for a while.

• If possible deprecate the old behavior before you actually break it.

And even doing all that, breaking changes will have their price.

Culture

The hard part about breaking changes is not to define them, or identify them. It is making a sensible behavior around them.

• Create a culture that accept their role in your product.

• Understand and gives the place for the price that comes with those changes on the clients.

• Encourage everyone on the pipe to identify and communicate the breaking change and its price.

• And then implement the guidelines in the correct way for your project.

I am working on a task I thought have passed from the world: Converting “goto” code to functional programming. And I am doing it in modern Javascript code.

This was covered by articles over 20 years ago, see http://ieeexplore.ieee.org/xpl/articleDetails.jsp?tp=&arnumber=126773&url=http%3A%2F%2Fieeexplore.ieee.org%2Fxpls%2Fabs_all.jsp%3Farnumber%3D126773

The basics are the normal loops, conditionals, break and continue.

Conversion rules

• If you have a goto that jumps forward can be replaced by a simple if on the code it jumps over.

• A goto that jump backwards is converted to loop. either a do-while loop, or an infinite loop.

• Several jumps forward with overlapping skipped code can be made using flags, each goto condition will set the appropriate flags, and the code execution will depend on the flags.

• Multiple jumps backward can be replaced by a single infinite loop, and appropriate flags.

In general, it is best to understand what the code tries to do. There is usually a better way then just make it work with the new tools.

Readability

I am a firm believer of making code readable.

Readable code helps everyone, including the person who wrote it, to get into the code. Makes it easier to understand the logic, easier to fix bugs when you need to, and easier to re-factor if necessary.

There are basically two approaches:

• Make it readable to everyone - by making it as simple as possible and as close as possible to English.
• Make it follow a project convention.

You can see that the first option is a specific case of the second. Only the convention is very low level, with the attempt to target as many people as possible.

Up until now I always practiced the first option. Both in the companies i worked for and in my personal projects. And was confident that this is the correct route to go by. Right now i am in a company where i need to learn the convention used by the company. And this forced me to rethink my approach.

When I look at large projects, they all develop their own convention. Even if the developers strive to keep the code readable to everyone. The introduction of library functions, utilities, custom markup tags… all generates a new convention, one that is project specific. Anyone who try to get into a large project, have to understand enough of those project specific building blocks in order to be productive.

On the other hand, right now I have to face one of the steepest learning curves i have ever had to climb due to this project specific convention that I have to get used to.

In my case the major thing i have to get used to is condensed code. No spacing, no unnecessary characters, no comments, no empty lines. And did i say it before: no spaces. even between sections of code that have different roles.

Comparing apples and oranges

When you compare the two approaches you get the following table:

Lets look at each factor.

Audience

For projects that target wide audience. Educational projects, open source project, the wider the audience who can read the code, the better. For closed in house projects, the company really care only that the people inside the company will be able to easily get into the code, so it becomes a non-issue for them. Unless they have plans to open the code up in the future.

Learning curve

This is a clear cut. In every project, people change and new people need to come in. The steeper the learning curve is, the harder it is to get new people into it.

Code size

This is another clear cut. Smaller code means less bugs, and less to read and understand.

Conclusion

The bottom line is that whatever you will go by, you will make a compromise. Just make the right compromise for the project you are working on.

We are programmers, and we get paid to write code. And we all faced the situation when we get in someone else’s code (could be mine from a few hours ago, I am evolving you know) and see code that hurts my eye.

So when should I fix it?

Here are the 10 commandments:

• if it works and this is an area you don’t need to touch. Don’t touch it.

• if touching it is a long and hard refactor, think long and hard before jumping into it.

• if the change is not covered by tests you already plan on doing. Consider the test workload addition. Automatic tests coverage is great, if you are certain it cover the necesary scenarios.

If you are already in the code, and the added workload is ok, then go and refactor like crazy.