4 Ways That Words Matter in Software Development

There is an art to language in software development. Creativity in analogies; defining a dictionary through a ubiquitous language; writing clean and intelligible self-documenting code; and paying attention to detail through proper spelling of words are all important when it comes to communicating, designing, and developing high quality software.

Analogies

I recently watched my five-year-old son work through an activity book. One of the activities was to decode a message that used symbols to represent letters. He looked up each symbol to discover what letter it represented, eventually decoding the entire sentence.

In a way, analogies are tools used for decoding messages. They are used to help discover what something means or someone is saying by comparing unfamiliar things with things that are relatable. Finally, a connection is made without having to fully understand the original things themselves. We do this a lot in the world of software to explain things to people who need to have an idea of what is going on behind the scenes. It’s a way to simplify the complexity of the detail for them by relating it to something they are familiar with.

This is a skill that starts to come natural after doing it so many times. It is very helpful for communicating with stakeholders of whatever software or architecture is being worked on. Stakeholders being individuals vested in the software.

Ubiquitous Language

In the world of Domain-Driven Design, one of the major strategies is to develop a ubiquitous language between developers and stakeholders as defined by subject matter experts. The developers, and anyone else who needs to take part in the conversations, learn the language of the users as it pertains to the software.

When first getting into the world of EHR software, the company that I worked for used the word “Visit” a lot. It quickly became evident that “Visit” was being used to represent multiple different concepts in different domains. It was used to describe an appointment in the scheduling domain, a progress note in the clinical record domain, and a charge in the billing domain. The word “Visit” is fine to use if kept in the context of its own domain (where each has its own ubiquitous language), but using the more specific terms removed a lot of confusion when discussing the system at a higher level.

The goal from here is for the developers to design, write, and refactor their code using this ubiquitous language. By following best practices, the code will read in a way that even the non-developers that know the language can understand. This leads me to the topic of self-documenting code.

Self-Documenting Code

Self-documenting code is the concept of writing code in a way that it does not need any comments to quickly understand what it is doing. This can be done by following some best practices.

One best practice is the careful naming of classes, variables, and methods. For example, if you want to know if a patient has a copay due so that you can bill them, you would have a piece of code that reads something like

if( patient.HasCopayDue() ){ Bill( patient ); }

As you can see, all the details are hidden behind the language that describes what is being done. This is what is meant by self-documenting. This is easier done when developers follow the Single Responsibility Principle. This is the concept that every method does one thing, and one thing only. It is easier to write code to lay out like sentences when the functionality is broken out in this way.

When a developer’s code spells out what it is doing, there is less need to write comments that will eventually be outdated as changes are introduced. This helps prevent having comments that eventually lie to you about what the code is doing due to any miss of maintaining them.

Spelling

Although it seems like it wouldn’t have a major impact, It is helpful when words are spelled correctly. Not only at the user interface level, but also in the project, class, variable, and method names as well. It helps when trying to search for sections of code that might involve a specific word. It also helps when you are reading code.

This isn’t about not knowing how to spell a word. This is about spelling an obvious word incorrectly, and not taking the time to go back and fix it. Developers may not be English majors, but a little effort goes a long way in keeping professionalism and pride in the code that we write. I find that misspellings indicate a slight lack of effort. Left unfixed, I believe that in the smallest way, it can perpetuate the same lack of effort into a micro “broken windows theory” series of actions that represents a slow leak of quality. With the refactoring tools available to us today, it takes a couple of seconds to fix.

I’m really hoping that I didn’t misspell anything in this document.

4 Ways That Words Matter in Software Development was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.