Avoid Specifying Internal Technical Implementation Details

« Table of Contents »
Previous « Software Component Context Is King

The Behaviour Specification Handbook

General Tips

Avoid Specifying Internal Technical Implementation Details

There is no need to specify the internal technical implementation details of a software component in the Behaviour Specifications. To be very clear, let me emphasise the word “internal”, in contrast with any publicly exposed, outward-facing behaviour or other mandated functionality, such as business rules.

If the implementation of a component needs to be refactored or changed, the words used in the Behaviour Specifications should NOT need to be changed. The words used in a Behaviour Specification should only need to change if there is a change to a “core business requirement”.

Behaviour Specifications can become unnecessarily brittle and potentially short-lived due to tight coupling that is created when any internal technical implementation concerns are specified. In other words, if internal technical implementation details are specified in the Gherkin, then the cost of maintenance and future enhancements will increase unnecessarily, since it could have been avoided in the first place.

Internal Technical Details — Example #1

For example, say that the low-level technical design has identified there is a component that must store and retrieve items in memory. Perhaps the component uses a Dictionary data structure to store the data, or alternatively, perhaps it uses an Ordered List data structure.

In this example, the type of data structure internally used by the component is completely irrelevant, and the fact that a data structure exists at all also is completely irrelevant in the Behaviour Specification. The only concerns that are relevant are the behaviours related to successfully and unsuccessfully adding and retrieving items, and also perhaps some non-functional performance requirements.

Internal Technical Details — Example #2

In this example, say that there is a behaviour specifying that a component should persist its data, but it unfortunately also says the words “in a database”. The word “database” is an internal implementation detail that makes the Behaviour Specification unnecessarily brittle. If in the future, the implementation is changed to store the data in a file in a file system, the wording of this Behaviour Specification also would have to be changed. This is inefficient, costly and can be avoided!

Alternatively, the wording “data store” is an example of a preferred, generic term that cleverly encapsulates any changes or volatility in implementation. When using the words “data store”, if the internal technical design of the component changes from using a database to storing the data in a file, the wording of the Behaviour Specification does not need to be changed. A behaviour that says “data store” instead of “database” is more resilient to future implementation changes.

Internal Technical Details — Example #3

In the example descriptions in the earlier section What Is A Behaviour Specification Description?, hopefully you noted that there is no indication of how the behaviours are technically implemented internally. In fact, just by reading those descriptions, you would not even know that they are specifically describing the behaviour of a User Interface component. That is intentional! Unlike many Gherkin examples that can be found in BDD literature, there is no typical User Interface wording about “screens”, “pages”, “fields”, “buttons”, “clicks”, or “navigation” etcetera, nor is there any need for those types of words.

These same behaviour descriptions could be copied as-is and used to specify a Web Service component as well as a User Interface! This is a prime example of why the software component context is king — the Behaviour Specifications of related functionality that exists in components separated by an architectural tier can be the same, and it is only the technical implementation specific to that tier that is different.

Internal Technical Details — Example #4

The example descriptions in the earlier section What Is A Behaviour Specification Description? also do not specify the particular technical mechanism by which the address validation service is invoked — for instance, as a Web Service call. That would be internal implementation detail!

It is possible that the solution delivery team could decide it is best in the short-term to implement a tactical solution. In this example, that tactical solution is chosen to be a monkey that physically runs down the corridor and hands a human a piece of paper that has an address printed on it which is to be verified. Whatever tactical or strategic approach is taken, the Behaviour Specification wording should not need to be altered!

To recap, it does not matter how the behaviour is implemented internally within a component. The wording of the Behaviour Specification should only need to change if there is a change to the core business requirement. Behaviour Specifications should be long-lasting and resilient by encapsulating internal implementation volatility. For anyone who is interested in the current, actual technical implementation details, that can be understood from and seen in the test run output.


Next » Specify Relevant Business Capabilities