User language inside the source code - The Ubiquitous Language

"We understand each other"  (James Shore)

http://jamesshore.com/Agile-Book/ubiquitous_language.html

• Does your source code lack knowledge?
• If one of the developers on your team left work now, would others be able to make sense of it?
• Is it a multiple lined mess, impossible to understand even for the one who wrote it?

Software development is by its nature a series of translations and compromises. What the end user wants, what the customer is willing to pay for, and what is technically feasible rarely combine to form a unified set of features. A deeper understanding between technical and non-technical people is needed, in particular at the communication divide between Stakeholders and Developers.

The LiveSource Toolkit helps you to develop a domain-specific ubiquitous language inside your source code and shows you how to use your codebase as a source for your requirements and documentation, improving communication for the whole team.

"Programmers should speak the language of domain experts to avoid miscommunication, delays, and errors. To avoid mental translation between domain language and code, design your software to use the language of the domain. Reflect in code how users of the softwarethink and speak about their work. One powerful approach is to create a domain model. 

The ubiquitous language is a living language. Domain experts influence design and code and the issues discovered while coding influence domain experts. When you discover discrepancies, it's an opportunity for conversation and joint discovery. Then update your design to reflect the results."   (Ubiquitous Language in 99 words - James Shore)

End Users are Ubiquitous

Not every software project has a dedicated business analyst or a domain expert. But every software must have users. Also, every software should be written for the users.

In general, on a development team the technical language is understood only by developers, the domain language normally understood only by domain experts. But, to achieve success, the end user language should  be understood by everyone. The end user language should be the ubiquitous one.

User Language good in Code?


The whole idea behind an ubiquitous language is that it is pervasive everywhere; in all project related communication, all the way down to the technical level. The idea is to preserve the business intention in the code and have the code mirror the real world as much as possible.

Source code is a little more limited in that you have to avoid keywords on a programming-language-specific basis, but other than that, the advantages are numerous; the programmers don’t have to make the mental translation from the language of code to the language of the domain resulting in less bugs, the domain experts don’t have to read the “Gang of Four” and can more accurately describe their needs, and both programmers and domain experts should be able to understand the end user's language. Driving the design based on the domain in this manner shows how closing the gap between domain and programming language leads to better code.

Most Agilists agree that a shared (ubiquitous) language improves communication between technical and non-technical people. Ensuring a strong tie to the code reinforces the language and ensures it's thorough use.

A User Story BEFORE and AFTER Ubiquitous Language

When the ubiquitous language is already being applied in high-level documents of the project, makes it much easier for developers to identify which technical jargon should be avoided in the source code.
Notice how the two stories below may communicate the same message, even if the domain language is being directly applied to the second one.

(Excerpted from a Tic TacToe Game)

BEFORE    Move      When the user clicks on the grid,      the system shows 0 or X depending on which one is the current user.

AFTER    Player Move When the player clicks on the game grid, the game shows the symbol 0 ou X depending on which one is the current player.

A class BEFORE and AFTER Ubiquitous Language

You will probably notice that it becomes easier to understand the code when you use

domain language while programming. There is much less guessing on the programmer's

intent, eliminating a lot of confusion for the one that is going to maintain it.

(Excerpted from a Tic Tac Toe Game source code)

BEFORE      /**  * Add the string O or X to a cell in the grid. */ public class  ShowCellGrid{ public static void  displayUser (Grid grid, Cell cell) {             if (!Initialization.flag   && Initialization.gameStatus.getSequence() == null   && isEmpty(grid, cell)) {  Initialization.flag = true;  String mk= showString(Initialization.gameStatus        .getCurrentUser().getUserString());  grid.setHTML(cell.getRowIndex(), cell.getCellIndex(), mk);  Initialization.gameStatus.getStatus()[cell.getRowIndex()][cell .getCellIndex()] = Initialization.gameStatus .getCurrentUser(); GameEnd.checkEnd(Initialization.gameStatus, cell.getRowIndex(), cell.getCellIndex());        } (...) }

AFTER    /** * Performs a move in the game. */ public class  PlayerMove { /** * When the player clicks in a cell, the game draws an O or a X on the     *  game grid depending on which player's turn it is. */ public static void   makeMove  (GameGrid gameGrid, Cell cell) {         if (!GameInitialization.waitingMoveFlag && GameInitialization.currentGameStatus.getSequenceWinner()  == null && isCellEmpty(gameGrid, cell)) { GameInitialization.waitingMoveFlag = true; String marker = showPlayerIcon(GameInitialization. currentGameStatus.getCurrentPlayer().getPlayerIcon()); gameGrid.setHTML(cell.getRowIndex(), cell.getCellIndex(), marker); GameInitialization.currentGameStatus.getGameMoves() [cell.getRowIndex()][cell.getCellIndex()] =  GameInitialization.currentGameStatus.getCurrentPlayer(); CheckWinner.checkForWinner(GameInitialization. currentGameStatus,cell.getRowIndex(), cell.getCellIndex());         } (...) }

Now, which one below would a Stakeholder better understand?

The contents of both tables below were extracted from the classes above.
Small changes in this matter has a huge impact on the code's general knowledge.

What we demonstrate here is that, once developers begin to introduce Ubiquitous Language 

within their source code, a lot of possibilities like filtering and searching becomes possible 

and useful to others who do not necessarily understand the technical terms.

(Excerpted from a Tic Tac Toe Game source code)

BEFORE    Show Cell Grid    Add the String O or X to a cell in the grid. Display User        Is Empty

AFTER    Player Move    Performs a move in the game. Make Move        When the player clicks in a cell, the game draws an O or a X on the game grid depending on which player's turn it is. Is Cell Empty        The Player can select a cell only if it wasn't already selected yet.

Using Ubiquitous Language in source code may seem simple, but it's not. In fact it implies a big paradigm shift for programmers who are accustomed to use their technical terms back and forth, as examples "EntityBeans","AssyncronousCalls", "DTO's ", etc...

Replacing these terms (which often not even other programmers can easily understand) and using words that are more self-explanatory in a Stakeholder's perspective, demand time and a lot of refactoring by programmers. It will not be in a day for code to become ubiquitous. A gradual and continuous progress is to be expected.

And speaking of self-explanatory words, the ideal nomenclature to use in a code is one that, when you are explaining the software to someone, it doesn't require saying another word beyond the proper nomenclature itself. For example, a variable should be called "Connection" or "DatabaseConnection"? A function should be called "IsNull" or "IsEmailEmpty"?

 No Rights Reserved. Please copy us!