This article,the second of a series of articles discussing Software Quality, is concerned with semantics and its importance in building maintainable, extensible and robust software systems.

“It is extremely important for a satisfactory result of any design to spend time on the search of the accurate and essential meanings, investigate their complexities, learn about their ambiguities, understand the context of use to better define the parameters within which we will have to operate.” Massimo Vignelli

In some senses it is difficult to write this without paraphrasing much of what Vignelli had to say about semantics; it is so obviously applicable to software. However, there are specific considerations when building a software system that are worth addressing.

Its Just Semantics!

There are some developers, project managers and business analysts who consider semantics not worthy of consideration and cry, “Its just semantics!” when wiser individuals are attempting to fathom the meaning of a thing. I agree, it is semantics, the computer does not care and will faithfully produce the same result if fields, methods and classes are named a, b, c or _fG. It would be ridiculous to do so and not even a nay-sayer would suggest doing it.

So what are they saying? Do they claim that precise semantics are unnecessary and attempting to be precise is an intellectual or academic exercise that wastes time and delays the important typing of code? The answer is usually something involving words like pragmatic.

There is nothing more pragmatic than defining a clear language for a system so that communication between all stakeholders, present and future, is unambiguous and clear. Lack of clarity has cost businesses millions, and will continue to do so until more care and attention is given to semantics amongst other things.

For example, it is fundamental to any Order Management System that it calculates the price of orders correctly. One would expect to find clear definitions in both existing software and in the minds of business people. But not always!

During the development of an Order Management System for a bank we found many errors and misunderstandings around pricing. Building this part of the system took much more effort than it should have done because terms meant different things to different people, or were not understood by some stakeholders. Sometimes, depending on the context, one knew what was meant. The lack of clarity had caused confusion and bugs in the older system we were replacing that resulted in incorrect pricing.

It took a beginners mind, some humility and a little embarrassment for the real model to emerge, but this was a small price to pay given the risks involved.

As an aside, it is disconcerting to think that traders and sales people in banks do not know how to price the most basic instruments. The crisis in banking goes deeper than a few traders and board members which is something for another blog.

Users and the Domain

Users are domain experts but sometimes they cannot answer all the questions about semantics asked of them. The meaning of many things becomes so embedded in their everyday work that its hard for them be as precise as necessary for a clear model to be built. Sometimes, questions will lead users to realise that there might be better ways of thinking about what they do and how they do it. Other times, different users have different words for the same concept and so agreeing a common set of terms for the system has the added benefit of clarifying communication between users and other stakeholders.

The Missing Term

Users often believe they have told the software team everything needed to implement something. But, problems arising during implementation lead to the conclusion that there is something missing. After further discussion, someone will use a word or phrase in passing that the team hasn’t heard before. A lightbulb moment! There was a missing term! After further questioning everything becomes clear and the implementation falls out perfectly.

The Misleading Term

Terms used by users can also be wrong and imply behaviour that is not correct. As an example, I recently worked on a project that had the concept of a period, something that had a start date and an end date. This concept was one users had been using for years. Simple, isn’t it?

Problems started to occur as the system evolved and questions about how this period worked with the rest of the domain became difficult to answer. Eventually, we realised that the period wasn’t a period at all and that the arbitrary restrictions thought necessary as a consequence were not commensurate with the desired behaviour as a whole. Everything became much simpler when the period became an end date. That was all that was needed. The model became simpler and easier to work with, and new behaviour simply dropped into place.

Now some may consider that last example a little trivial and it is. But the effect was that software was written that did not need to be and the client lost money and time as a result. The sum of these small things adds up. After all, software is the sum of small things, and so bold steps must be taken to eliminate these problems if a high quality, malleable, evolvable system is to be built.

Methods and Functions

As the domain evolves and its semantics become understood, so will the operations carried out on the domain. The semantics of those operations are as much a part of the domain as terms, classes and other concepts.

The names of operations should follow the terms and phrases used by the business as much as possible. What is done to something is the concern here, not how.

Continuing the Order Management System example: users will talk about filling an order, or perhaps booking an order. So I would expect methods on Order (in an OO system) called fill, or book. I would be disappointed to see methods like setState(int bitMask)! It is all about the intent.

Naming operations after how something is implemented is the path to madness because the how will change over time. Software developers after you will want to know what you are doing to something, not how it is being done, they can see how by reading the code.

The Broader Context

A software system, and its users, do not sit in isolation in an organisation. People in an organisation have a culture and language all of their own that their systems should reflect. When building something new, it is important to reach beyond the system in question to obtain an understanding of that wider context so that the new system will sit comfortably amongst the others.

The meaning of the new system must be coherent with others to avoid confusion, wasted time and effort, and potentially a financial cost to the client.

Vulgarity

There are those who simply do not understand that semantics are important. They do not care about the people that come after them or that the system is ugly to behold. All they are concerned about is that the right kind of result appears to come from their work. This behaviour is crass and vulgar; Vignelli puts it well:

“Vulgarity implies a blatant intention of a form of expression that purposely ignores and bypasses any form of established culture.” Massimo Vignelli

There is an established culture in software of producing maintainable, malleable, understandable software that conveys its intent at all levels and, critically, behaves so perfectly for its users that it is almost invisible. This culture is being fostered and developed by people particularly in the agile methods and software craftsmanship  communities which can trace their roots back to the 1960s.