How to build a shared vocabulary of the project terms on a developers team?

Question

When I work on a developer team (3-10 people), I often notice that getting a precise and shared definition of each what each term in code means becomes an issue as the code base grows.

After a few monthes, two totally different concepts can use the same name and two same concepts can use synonyms. It hardens a lot the code reading and the integration of new developers.

I take the example of the coding of an email client.

Here are the most frequent issues after a few monthes:

• Business model vocabulary is mixed with UI and technical vocabulary (ie : The Text UI View of the email client and a Text attribute of an email model)
• Developers translate a same concept differently (ie. Email class in the detailled view becomes Message in the ListView - but it stills use the same attributes)
• Approximative and unshared translations of the model between developers - sometimes due to a lack of english vocabulary that leads to too frequently used terms (ie. Item, Text, Label, Button, Manager, Handler...). These terms sound good, but it is hard to get a precise shared definition of them without talking about it among the team.
• Misunderstanding of the business concepts - that leads to mixing business concepts in a unique class and to break Single Responsibility Principle.

Appart from documenting a lot before coding (which sometimes is not suited for Agile development) - are there any methods to share both business and technical vocabulary among a team during dev ? So that each person has an clear knowledge of what involves a word - not in general but in the project and code context.

Answer 1

Code reviews and pair programming are some of the better tools to address these issues as you get more eyes on the code and can collaborate better to make your naming more standardized. You will have to discuss and have an agreement over what terms need to be defined or constrained to a specific scope. I'd recommend starting small with about 5 or so naming you feel cause the most confusion and working from there. It would help to have some form of documentation you can point to as the source of truth that can be pointed to. Keep in mind though that the more terms you try to limit, the more likely it is that developers will start to ignore any documentation, or developers may feel that all of their preferred terms are being discounted.

Solutions to this problem are political and you need buy in from everyone to avoid any one developer from feeling like their contributions are being discounted because you don't like how they name things. Efforts to standardize things like this are good intentions, but they are also great ways to have several standards all partially followed making your code as bad or worse than it was before.

Answer 2

I didn't know what Ubiquitous Language means, and it seems to be what was missing to address my issues.

• Business model vocabulary is mixed with UI and technical vocabulary (ie : The Text UI View of the email client and a Text attribute of an email model)

  Single Responsibility Principle of classes : have a rule to not store any business attributes in a View class and to not manage View in a business class

• Developers translate a same concept differently (ie. Email class in the detailled view becomes Message in the ListView - but it stills use the same attributes)

  Ubiquitous language with a shared translation table of the domain terms if domain isn't in English. Talk with experts of any missing term to know the way they would call it

• Approximative and unshared translations of the model between developers - sometimes due to a lack of english vocabulary that leads to too frequently used terms (ie. Item, Text, Label, Button, Manager, Handler...). These terms sound good, but it is hard to get a precise shared definition of them without talking about it among the team.

  Translation table again, and a precise team definition and criterias of what are Handler, Manager,Label and other technical terms...)

• Misunderstanding of the business concepts - that leads to mixing business concepts in a unique class and to break Single Responsibility Principle.

  Talk with experts, ask PO to be specific about the terms used in the stories and in doubt ask clear definition. Eventually write definitions