The Art of Naming Things
“A wise man once said, ‘Software development is no more and no less than the art of naming things.’”
Jon Goldman, an outstanding software developer whom I once worked with, must have said this to me a hundred times. And since then, I must have repeated this great variation on the Phil Karlton quote a hundred times myself.
How can good software be written without a common definition of each term?
Imagine a lender that collects data from a potential borrower, credit reporting agencies, and other data sources. The underwriter reviews the data to decide whether to make the loan or not. The developer may think of the data as a “loan application” whereas underwriting refers to this data as a “package.” The sales team may refer to the data as a “sales opportunity.” One set of data; three terms.
The sales team may use the term “loan application” for the piece of paper signed by the potential borrower. And the funding department may call the paperwork they send with the funds a “package.” Two of the same terms, but used in completely different ways!
Misunderstandings lead to defects—and to general discord between people who are all convinced that the person in the next department doesn’t understand how the business works.
Shared names are essential to shared understanding. Accurate names are important too. Well-chosen words create clarity.
Teams that invest time carefully choosing terminology improve their ability to work together. Spending the time to be very specific about what things are and are not may slow down the requirements gathering process, but it is time extremely well invested. By gaining agreement on what each data element is and should be called, you can avoid communication problems and generate better requirements. Naming things carefully also contributes to good code quality by more accurately describing the business requirements to the developers.
Words have meaning and use of the proper words sets proper expectations. Once you agree to your terminology, use it everywhere: In requirements documents, emails, the user interface, code, and in the database schema. Not only does the care you take in choosing words pay now, it will also pay later. Future teams will have an easier time understanding and updating the system because they will more clearly understand what the code they are modifying does.
Image by Elizabeth Piotti. Photograph by Tim Arterbury.
