if you don’t have a good name for it, give it a bad name. a really, really bad name so you’ll fix it later.

Good naming is hard

Sometimes when writing a class, or occasionally even a method, I struggle to find a good name for it. After a while I give up trying to find a good name for it and chose something that is just about “OK”, a working title if you like. Unfortunately this tends to create poor generic names, such as “ConnectionManager”, that vaguely make sense, but can obfuscate the true purpose of the class. I’ve lost count of the number of times that I’ve heard developers say something like, “Oh, so that’s what that class does!”

The problem with these “OK” names is that they tend to have a strong inertia to change. Typically I have the intention of going back and renaming it, however the longer I leave it the less likely this is. If the name is adequate, but not great, then why go through the effort of renaming it? Sure, some IDEs, such as Eclipse, do a superb job at refactoring, however a lot of the code we write here at Caplin is in JavaScript and the tool support for this isn’t as good. Regardless of this, even where there is good tool support, there are time pressures, backward compatibility and other considerations that lead to “OK” names sticking.

Overcoming renaming inertia

This brings me back to Kent Beck‘s excellent suggestion. If you provide something with a really bad name the inertia to change it will be non-existent. You will have to change it before it becomes part of your public API or other developers have to use it.

The great thing with this is that it allows you to write your class and see what it responsibilities are before you provide its proper name. This should lead to meaningful names that define exactly what a class does, ensuring no one is surprised when they try to use it.

Personas are a tool we use at Caplin to help us REALLY understand who our users are and engage everyone in the company in building something compelling that will delight our users. No I am not talking about a sexy, gimmicky UI which when first stumbled upon people go “Wow”. I am referring to a product that seamlessly fits into the user’s life, compliments their day-to-day tasks and basically engages them to a level that they no longer can live without it.

So what is a persona?

A persona represents a group of users that hold the same goals – an archetype. These goals are not “I like to use this feature” BUT “what’s the end goal in an individual’s or company’s day/week. It’s only when we look outside the boundaries forged over time that we begin to really understand their needs. If you are passionate about doing this you will deliver products that delight.

The persona also includes people that are driven by the same motives, driving like-minded behavior with common frustrations.  Just think how powerful this is when developing a product. There will be no self-referential in a meeting room arguing, ” No, I think it should do this because that’s what I would like to do”, or “how cool would it be if we added this feature”.

EVERYTHING is referred back to the persona – does it help them achieve their goal? No? Then out. Yes, then how?  Design meetings become focused on making the persona’s life easier,  aligned to removing the pain points in their process. No swirling gimmicky feature just because the technology can do it, it has to add value to the persona.

At Caplin, we have found it has removed the ambiguity around the term “user” and has also been a great educational tool on who our users are. We are now seeing many developers refer to the persona by name in discussions and has really helped us “walk in the shoes” of our users and show real empathy during the development process.

The real power also comes when you use Personas with Narrative Journey Maps.

When an end to end acceptance test fails, the failure could be due to any one of a large number of source lines or expectations changes across a large body of code.  Debugging may be quick, but often isn’t.

Small tests run faster too! While a typical small test may take 10 milliseconds to run, a large acceptance test may take twenty minutes.

Just a small back of the envelope calculation tells us that if a developer checks in twice a day and saves an hour each time because potential issues had been found before check-in with fast small tests, and the faster feedback, or has reduced their time spent debugging – that is two hours a day per developer that could be put to better use.

2 hours a day * thirty developers * two working weeks = 600 additional hours per two week iteration available.

This is equivalent to adding seven and a half developers to the team!

What value do you get from tests of different sizes?

Ignoring this testing just generates projects which will fail – not may fail – will fail, categorically will fail!

There are two sets of tests that are critical here…

Good unit test coverage and a TDD approach to development ensure that the rest of the organisation is supplied with product that works as developers expect it to.

Component tests and functional acceptance tests ensure that the product does what the product owner expects it to.

• Practically, the only way to do solid testing on new features is to have a stable product.
• Practically, the only way to assure a stable product is to either have solid regression testing on each release or to not make any changes.
• Practically, the only way to make sure that adequate regression testing is done is to automate the regression tests (unit, component, functional).

Without these tests in place, iterating quickly places an impossible to meet burden of verification demand on the testers and product owners, which just gives you a fragile process not an agile one.

Is your process Agile or Fragile?

Although four years can seem like an eternity within software development, I found this video extremely pertinent to what I find myself doing today. I have been following the principles of Test Driven Development (TDD) for many years now, however this is the first time I have really delved into Behaviour Driven Development (BDD). I would thoroughly recommend watching the video if you have 45 minutes to spare, however, if not, I have summarised the notes I took whilst watching it below.

My Notes

• BDD is an evolution of TDD. Dave Astels described it as what TDD looks like if it is done well.
• When talking about unit tests, what is a unit? Is it a method? Is it a class? The definition of unit is ambiguous.
• BDD is attempting to move away from several of the words that Dave Astels believes have negative connotations after their use within TDD:
  • Instead of calling something a test it’s called a specification or spec for short.
  • Instead of using assertions we should use expectations instead. Anyone using mock objects will already be familiar with this concept.
• One of the key things to avoid is state based testing. Depending on the internal state of an object to verify a particular method works correctly breaks encapsulation, even if the test is intentionally meant to be friendly with the class it’s testing. This leads to fragile tests and creates a barrier to refactoring.
• The focus with RSpec was to make it readable. The writer and reader should not have to remember things like whether the first argument to the assertion is the actual or expected value.
• Although Dave Astels jokes that he has until version 1.0 to rename the should method with must it looks like he either lost the argument or changed his mind about it; RSpec is now version 1.3 and should is still being used.
• In TDD there is a tendency to create a one-to-one relationship between a class and its test. BDD says that we should be creating specs that verify a particular behaviour, rather than writing tests for each class and its methods. A coverage tool can be used to ensure that all possible code paths have been exercised.
  • The example that was given for this were the specs for EmptyCollection which might be “should return empty iterator”, “should have zero size” and “should return is empty true”.

Some BDD Frameworks

• RSpec – The BDD framework for Ruby that Dave Astels is talking about in the video.
• JBehave – A BDD framework for Java.
• JSpec – A BDD framework for JavaScript.
• Cucumber – A BDD framework with implementations in various languages, including Ruby, Java, .NET, Flex and web applications.

Please look here for a more comprehensive list.

Previous to starting at Caplin, I was the European Test Engineering Manager at Google. While there I gained a few helpful tips to encourage ongoing learning, brainstorming, discussion and a bit of entertainment despite the typical time constraints of a busy testing environment.

One of these ideas is regular tech talks. I find a short mental break from my usual week looking into something completely different can spur a number of interesting ideas and some excellent discussion amongst participants.

The Caplin Tech Talk Series

We introduced Caplin’s Tech Talk series in October. These weekly(ish) talks have proved to be a great success, with attendance from across the company, not just from the test team.

The Tech Talks usually begin with either a live speaker, or a video from the internet, with questions and discussion during and after. While the the videos are valuable, it is often the resulting discussion that makes them worthwhile. We’ve generated a lot of great ideas and the discussion is often animated and thought-provoking. Thankfully, not quite as animated as when the Blues Brothers play “Rawhide”

At Google, tech talks are done with a live speaker, and often recorded for posterity. Many of these are available on YouTube and Google Video. Other sources of good videos are the Yahoo developer channel, various conference videos (e.g. James Lyndsay, Brian Marick, James Gosling), TED, etc.

Most of the talks are technical in nature to suit the general audience though we do throw in a couple of more general productivity, business focussed or more general interest talks.

We originally launched the Caplin Tech Talk series with the following few topics, trying to get a mix of things to interest a broad range of people.

• Misco Hervery – The Clean Code Talks – Mr Untestable!
• iPhone Game Development Channel - 71Squared
• GTAC 2007: Simon Stewart – Web Driver followed by the Steel Cage Knife Fight.
• JavaScript: The Good Parts – Doug Crockford
• Brad Neuberg — Introduction to HTML5
• Linus Torvalds on git
• David Allen: Getting Things Done (Knowledge Work Athletics)

We encourage ideas from the across the company, and have often discovered really interesting talks based on these contributions.

Recently we had a “Productivity Theme” where we watched Allen Hutchison’s ‘fireside chat’ with Tim Ferriss, author of the “The 4 Hour Work Week” and discussed some of his concepts including Manufactured Emergencies, Personal Outsourcing and Testable Experiments. Because the topics lend themselves to a wider audience we got a really good turnout and some useful discussion.

Occasionally, after a talk, we will watch something light-hearted for a couple of minutes… e.g. Bobby McFerrin at TED, or “Hitler’s Nightly build fails”

What talks have you seen that were great?

Frequently accuracy and precision seem to be considered the same thing. The critical difference was highlighted when I went on an agile course run by Mike Cohn. He demonstrated the difference by asking the question of when your birthday was?

I could answer this question by saying it’s in November. This is accurate and in some cases might be a good enough answer, however it is not precise and certainly wouldn’t help if you were planning on organising a surprise party. However if I had said the 2nd December I would have given a precise answer, although completely inaccurate.

What I have learnt from this is that in software development it’s more important to focus on making an estimate accurate, rather than trying to be precise. I like the approach taken in planning poker where there are quantized buckets that your estimates can fit into. The difference between a story being sized at 1 story point and 2 is huge; the second is twice the size of the first.

However the difference between a story sized at 20 story points and 21 is insignificant. In fact, how can we possibly tell that one is marginally larger than the other? There is also a danger that the extra precision suggests a high level of confidence in our estimates, which, in my experience, just doesn’t happen in software development. In this case it makes more sense to estimate both at 20 story points and allow velocity to work its magic of how much work to take on during a sprint.

At the end of the day it is better to be imprecisely accurate than it is to be precisely inaccurate.

Of course at times the estimates have been inaccurate, with features taking far more time to implement than was initially predicted. The question is how to learn from these experiences to help improve your estimates. This is especially pertinent for software engineers within financial services because this same conundrum is at the heart of pricing financial instruments.

This article looks at how the Rational Expectations Theory can help you improve your estimates in software development. It starts by looking at estimating something much easier than a software enhancement, your journey time into work, and demonstrates when that estimate should be considered good or bad. It then looks how this can be applied to software development.

Rational Expectations Theory

A few years ago, I was introduced to the Efficient Market Hypothesis whilst reading about how stocks are priced. This hypothesis is built upon the Rational Expectations Theory. Paraphrasing this theory, it states that an individual bases their estimate on:

1. Their rational outlook
2. All the available information
3. Their previous experiences

Although both the hypothesis and the theory are out of favour with many economists, the principles of rational expectations struck a chord with me.

Rational Expectations applied to Journey Times

To demonstrate rational expectations in practice, consider the question of how long it will take you the next time you travel into work? Assuming that you don’t work at home, aren’t starting a brand new job and haven’t just moved homes, then this is something that you should be pretty good at. After all you have an abundance of experience making that journey.

My estimate for my door to door journey time would be an hour. However there is a pretty big deviation between my fastest and slowest ever times. Every now and again my interconnections align perfectly and I can make the journey in 45 minutes. On the other hand, it has taken me 3 hours when my train broke down and, to compound matters, the tube line I needed to complete my journey was closed.

Rational Expectation Theory says that estimate of 1 hour is good because it is the equilibrium of my times. An estimate of 45 minutes would be bad because it’s overly optimistic and I’d rarely expect to meet it. An estimate of 3 hours is also bad because it is too pessimistic since it has only occurred once, and the circumstances were exceptional.

The theory also states that the estimate is based on all available information. My estimate of 1 hour would no longer be reasonable if there was a weather forecast for tomorrow predicting snow. In Britain snow is renowned for crippling the travel network. It doesn’t matter whether I have heard the weather forecast or not, it is my responsibility to find out all relevant information to aid my estimate. Ignorance is no excuse.

Rational Expectations applied to Development

I like the Rational Expectation Theory because I think its three rules capture the essence of what estimating in software development is about. Prior to reading about the theory I didn’t think too much about how I came up with an estimate, it was pretty much a gut feel. Now I realise that subconsciously these rules were actually what were going through my mind. The theory helps me to break the estimate into its constituent parts.

Applying the theory to development leads to these conclusions:

• Two features on the backlog, in the same area of the code base, with a comparable depth and level of complexity should have similar estimates.
• Knowledge about how easily a new feature might be implemented within the current code base is important. If you know the code will need some refactoring in order to implement the new functionality cleanly, then this should be allowed for. Of course the law of diminishing returns applies here; familiarity with, rather than intimate knowledge of, how the feature might be implemented will be good enough in most cases.
• Allow for your past experiences with your code base. Take the case where the two similar features have been sized at 1 day (or story point, or other unit of measurement). Whilst working on the first you uncover some unexpected issues, and it ends up taking 4 days to complete. Does it still make sense for the second item to still be sized at 1 day? The answer to this depends on which of these two scenarios the overrun fell into:
  1. If the reason it took much longer to complete is systematic and likely to affect the estimates for all the other features, then project velocity will be able to compensate for it. The relative sizes of the estimates are still the same.
  2. If the reason was localised to the code surrounding that feature then it is only rational to keep the estimate at 1 day if I believe that the problems were an anomaly and won’t impact the other feature.

Well, that’s nice in Theory…

I find that the Rational Expectation Theory is a useful reminder of what to do when estimating, however in software development we are never building the same thing twice (we are DRY here aren’t we?). As a result the idea of an equilibrium point is non-existent; we are dealing with a unique piece of development with a sample set of one. However a lot of the time we are doing similar things that we’ve done before, so we do have a reasonable point of reference for comparison.

When is an Estimate bad?

In my example of a journey to work I estimated that it would take an hour. I should be pretty good at knowing how long this takes since I have made the journey over 2,000 times. If the journey takes me an hour and a half tomorrow does that make it a bad estimate? That depends. If there was planned engineering work causing a reduced service that I could have found out about in advance, then it was a bad estimate. I should have allowed for the impact of the engineering work. If the delay was caused by my train breaking down then the estimate was rational and therefore wasn’t bad. After all, it is just a estimate, not a guarantee.

The same logic applies to estimates given for development. We never have the luxury of having written exactly the same functionality many times previously, but there are often significant overlaps. Provided that your estimates are rational, then you can be confident that things should average out. Some features will take longer to write than estimated whilst others will take less time. Also don’t be afraid to re-estimate specific features if fresh evidence comes to light that shows that the estimate for a particular feature is irrational.

Afterthought: A World Free of Estimates

At Caplin we have spent the last few months trialling Kanban with several of our internal development teams, which offers a idyllic world where estimates aren’t needed.

I am still trying to grapple with the implications of this, and am looking forward to understanding it better. My gut feeling is even with Kanban estimates will still be necessary at a high level due to the inexorable fact that the priority of some features will always be based on the cost to build them, which is a multiple of number of people working on it by the time taken by them to build it.

This article addresses the issue of how to identify, with confidence, whether an API is backwardly compatible or not. As I mentioned previously there are times when an API is just too incorrect to be kept, however the decision for a breaking change must be a deliberate one – not an accidental one that is typically only discovered when the users of the API find that their existing code no longer works.

Preventing Breaking Changes

It is easy to tell developers that they should keep an API backwardly compatible, however even with the best of intentions it is possible to introduce subtle changes to the behaviour, particularly if you are refactoring collaborating classes that may not directly be part of the public interface. Every developer should be aware of the importance of keeping the API backwardly compatible, however this cannot be relied upon. After all, every developer should be striving to keep their code bug free, but we still write tests to verify this.

The solution is to detect any API changes before it is released, preferably in an automated fashion, so that it can be fixed. The problem is how to know whether an API has actually changed.

Compilation

A starting point for a compiled language, such as Java, is whether some code that was written against the old API still compiles against the new one. Any interfaces that have changed, including those with changes to method signatures and so on, will be flagged up immediately by the compiler. However this is no guarantee that the behaviour of the API hasn’t changed, and this simple verification isn’t available for non-compiled languages like JavaScript.

Unit Tests

The next obvious tool to detect a change are unit tests. The problem with this is that the unit tests will also be updated when the underlying code is modified. The fact that a unit test for a public API is having to be changed should start alarm bells ringing for the developer making the change; are the changes that they are making backwardly compatible or not? Again, however, the problem with this is that sometimes the changes can be subtle and the breaking change may be missed, particularly if the changes are made to a collaborating class rather that the one that is directly part of the public API.

Acceptance Tests

Acceptance tests can be used to detect breaking changes in a similar way to the unit tests. My problem with this approach is that they tend to be less granular and therefore susceptible to missing subtle breaking changes. Ideally I want my tests for API changes to have excellent coverage and to test all possible code paths, which is usually something that isn’t done by acceptance tests.

API Tests

Taking a step back, it does look like unit tests seem a good match for solving this particular problem. The only issue is that the unit tests will be modified when the code is changed, which may mask any breaking changes that have unwittingly been introduced. However we do have a set of unit tests perfectly suited to this which haven’t been modified, those from our previous release. We know that they proved the API for that release worked, so if the same tests pass against the new code it stands to reason that we should be backwardly compatible.

Creating API Tests

At Caplin we have a set of API tests that are a specialised group of unit tests aimed at verifying that all aspects and behaviours of the public API have not changed. They are usually a subset of the unit tests written for a particular library.

Only Running the API Tests

The first problem is specifying which tests are those for the API and which are standard unit tests. This is important since the implementation of collaborating classes can be changed without impacting the public API. As a result the old unit tests for refactored collaborating classes may now fail, however these are unimportant if they have no impact on the API.

Within our JavaScript unit tests we have added the ability to flag a particular test as an API test. We can specify whether we want to run only the API tests or all the tests, including the API tests.

Alternate approaches would be to create different test suites for the API and standard tests, or perhaps to use a custom annotation like @ApiTest rather than @Test in JUnit 4.

Dangers With Mocking

One danger with testing APIs is the use of mock objects. Mock objects combined with dependency injection provide a powerful way to test the logic of a particular piece of code as a single unit, without having to rely on the real logic in the collaborating objects. Instead the mock object acts as a replacement for the real collaborating object, verifying that it is invoked in the correct way and returns the appropriate values.

The danger is that changes to the collaborating object, such as the addition of a statement that throws a runtime exception if an argument is null, will not be emulated by the mock object. These problems are not insurmountable, however you need to be aware of the potential risks. In the case above there is a reasonable argument that there should have been an API test written for the collaborating class that demonstrated that the arguments could have been null previously which would now fail.

Getting the API Tests

At Caplin we upload the API tests to our Maven repository along with the other build artifacts for our libraries. For example when we release version 1.0 of a library, the API tests for 1.0 are uploaded to Maven. When we are building version 1.1 of the library we download the API tests for 1.0 to verify that the API has not changed.

Alternatives to getting the tests from Maven are to use another dependency management system, to pull the tests from a branch or label from source control, or even copying them from a network share.

Updating API Tests

It is possible that a public API hasn’t changed, however the API test for it fails. The reason for this could be that the interaction between the API method and its collaborating objects, particularly if they have been mocked out, have changed, and the test expectations are no longer valid. As a result the code for the API tests will need to be updated.

This change needs to be managed via source control, with a new version of the API tests pushed into Maven, or wherever they are being stored.

Backward Compatibility With Older Versions

At the moment we are only checking backward compatibility against the previous version of the API. I believe that if an API is compatible with the previous one, and that previous one was compatible with the one before, and so on, then it stands to reason that the current API should be compatible with the oldest one.

Conclusions

We are still in the early days of trying out this approach, however the early signs have been encouraging.

Ultimately a large amount of the responsibility still lies with developers to ensure that their code changes to a public API maintain backwards compatibility. The API tests are a safety net that gives confidence that it really is backwardly compatible and provide an early warning of any breaking changes, allowing them to be fixed before a release is made.

Any breaking changes within an API must be a conscious decision, not an inadvertent one.

The evolution of software practices ebbs and flows over time, and it seems that Hungarian notation is currently out of favour. This is especially apparent with some of the new developers that have joined the team here at Caplin. One of the first questions they ask is often about the naming convention that we use.

Hungarian Notation is useful in JavaScript

I believe that an untyped language like JavaScript benefits greatly from Hungarian notation, allowing the intended type of a variable to be determined from its name. If I am debugging some code that is going wrong I can quickly check that the data associated with that variable is of the expected type. Also if I am writing new code I know which methods I can invoke on the variable.

The scoping within JavaScript is strange too. If a developer forgets to add a var declaration for a particular local variable within a function then the variable is added to the global scope, with the potential of nasty unforeseen side effects.

Caplin’s JavaScript Naming Convention

At Caplin, we have two components that are added to the start of the names of our JavaScript variables: one represents the type, and the other represents the scope.

Type Prefix

• b – a Boolean variable. We only expect it to have a value true or false. For example bIsVisible.
• e – a DOM element. Provided its not null we expect to be able to access childNodes and so on. For example eGridBody.
• f – a function pointer. Typically this will be invoked at some stage in the future. For example fCallback.
• m – a map. For example mPropertyNamesToValues.
• n – number, either a integer or a float. For example nColumnIndex.
• o – an object. We don’t try to differentiate between all the different object types we have defined within our code with dozens of different prefixes, this would get too complicated to remember. Typically we use JsDoc to identify the types, if the scope of a variable is not small enough to see its type. For example oObservable.
• p – an array. This should really use an a prefix, however this is a throw back to the original Hungarian notation from my C++ days where an array was just a pointer. For example pQueue.
• s – a string. Provided its not null we expect to be able to invoke methods like match(). For example sUsername.
• v – a variant, where various different types might be allowed. A typical example of where this might be used is a generic debugging method that is happy to take any type of argument and output it to a log. For example vValueToLog.

Scope Prefix

• m_ – private member variable. Although there are techniques to hide member variables there are performance costs associated with them. The m_ prefix is a gentle reminder that only the class the member variable is defined in should be accessing it. In fact, when the code is obfuscated these private members may also be obfuscated since they aren’t part of of the public interface of the class. For example this.m_sSubject.
• g_ – global variable. These are used sparingly. If a variable has a value to assigned to it within a method but does not have a g_ prefix then beware, this is probably a mistake and we now have an unexpected side effect. For example g_bIsDevelopment.
• All other variables, such as local variables or function arguments, have no scope prefix.

Horses for Courses

To be honest, although I use Hungarian notation throughout all of my JavaScript code, I avoid it altogether when coding in other languages such as Java. The reason for this is simply that Java is a typed language, and I don’t feel that this adds any benefit, however Joel Spolsky makes a great case for using it, even in the case of a typed language, in his blog Making Wrong Code Look Wrong.