Names for Ingredients (and Variables)

The use of clear variable names can help make code more readable and reduce the likelihood of mistakes.

"Excuse me. I am looking for powdered rose petals." said Marcus.

"On the shelf behind you." replied the young clerk without looking up. He continued to sit behind the counter, copying text onto a sheet of parchment.

Marcus glanced behind himself to confirm that he had already checked those shelves. Marcus turned back to the clerk.

"I did not see it there." responded Marcus. "In fact, I did not see any ingredients that I recognize. Everything seems to be encoded."

"Shorted," responded the clerk without additional explanation. Before Marcus could ask for clarification, the clerk hopped off his stool and walked around the counter. He proceeded up to the nearest shelf, selected a small bottle, and returned to the counter. He placed the bottle on the counter.

"That will be three copper pieces." said the clerk.

Marcus studied the bottle. It was labeled with large letters: "RP3p". He picked up the bottle and turned it over in his hands, searching for any other markings. There were none.

"Are you sure this is powdered rose petals?" Marcus asked.

The clerk nodded. "Yes. This one clearly states 'RP3p', which means 'Rose Petals Powdered'."

"I see. You abbreviated it. RP for Rose petals and p for powdered. But why the 3?" asked Marcus.

"There is more than one ingredient that can be abbreviated as RP. RP1 is 'Raspberry Puree', RP2 is 'Red Pollen', RP3 is 'Rose Petals', and so forth." answered the clerk.

"That is terribly confusing." exclaimed Marcus. "I have never heard of such a strange system."

A troubled look crossed the clerk's face. "It is my own scheme. It is more efficient." he explained.

"More efficient? You have to figure out awkward abbreviations in order to understand anything." objected Marcus. "It is a wonder that anyone can find what they need."

"But the abbreviations all make sense." responded the clerk. "They are all quite simple actually. How else would you abbreviate 'Rose Petals'?"

"I would not!" answered Marcus. "I would label each ingredient clearly with its proper name."

"But that is so inefficient." complained the young clerk. "Everyday, I have to copy hundreds of potions to sell to patrons. I have to do that all by hand. Do you know how much faster it is to copy potions with this new system? I save hours."

"My word!" exclaimed Marcus. "You sell potions that use this idiotic encoding? Are you serious?"

The clerk did not respond.

"Do you know how dangerous that is? What if one of your customers confuses rose petals and rabbit pellets? It could be a disaster!" argued Marcus.

"But it is more efficient." protested the clerk.

"For you… and at the moment." countered Marcus. "But it makes the potion recipes harder to understand. Worse, it makes it easier to make a mistake."

"But it is shorter." tried the clerk.

Marcus shook his head sadly. "I know it seems faster and more efficient now, but there is a high price for using such shortcuts. It is much better to use clear names. Trust me. I have confused ingredients before; it never ends well."

"You have?" asked the clerk.

"Yes. I once copied down a recipe with 'S' for Salt. Unfortunately, three weeks later, I mistakenly read it as Sulfur. S for sulfur seems quite reasonable. Needless to say, the bread tasted terrible. It was completely inedible."

The clerk did not seem to have an argument for that. "I guess that I could change them back." he said.

"Yes. You should." encouraged Marcus. "Now. Are you absolutely sure that this is the ingredient that I need?"

The clerk hesitated.

"I see." said Marcus. "I will be back some other time then."

And with that Marcus left the store. He turned down a side street and started for the "Potion Ingredients and More" shop on the other side of town. It was a long walk and the prices were higher, but he needed to be absolutely certain that he had the correct ingredients. The last time he had incorrectly mixed up a batch of magic soap, he had ended up smelling like a skunk for a week. There were some things on which he refused to take any chances.

---------------------

Also see Ann's experience with names in The Importance of (Variable) Names.

Or read more practical advice by Marcus in: The Importance of Unit Testing Magic Spells; Data Validation, Marcus, and the Minstrel of Cheese, or Version Control in Magic Spell Development.

The Importance of (Variable) Names

Having clear, meaningful variable names is an important factor in writing understandable and maintainable code.

By the time Princess Ann had reached the northernmost outpost within the kingdom, she was losing hope. Her father, King Fredrick, had sent her on a quest to save the kingdom from impending darkness almost a month ago. So far, Ann had found nothing. Meanwhile reports of roaming dragons and hordes of goblins increased throughout the kingdom. Ann felt completely demoralized.

The outpost of Garroow had been hit particularly hard by the recent chaos. The goblin attacks had been increasing in recent weeks. The commander, Sir Aat, had sent word to Ann's father that the outpost was in desperate need of reinforcements. At a loss for better stops on her quest, Princess Ann headed north to Garroow.

The situation in Garroow was worse than she had expected. During her first night at the outpost, a small goblin attack almost overwhelmed it. The fifty person garrison barely held off just three, relatively lethargic, goblins. She heard the captain shouting orders at his solders: “Ut, guard the South wall. No, I meant Ot. Ut, stay where you are.” “Drex, swap places with Plex, we need an archer on the wall not a blacksmith.” “Et, secure that door.”

Eventually, the soldiers repelled the attack and extinguished the fires. However, the lingering feeling of chaos and confusion continued to bother Ann. It worried her that the garrison's response had been so disorganized. It was like watching a turtle try to chase its own tail. The problem was not the number of soldiers in Garroow, but rather how they were being commanded.

Ann resolved to fix the situation before leaving the garrison. She spent the entire night pondering the different algorithmic strategies, certain that one of them would help the garrison run more efficiently. As she had been taught from an early age: almost every problem has an algorithmic solution. She debated the pros and cons of using dynamic programming to organize communication lines, using a min-max search to optimize strategy, and using randomization to avoid local minima. But none of these approaches seemed to address the core problem. Ultimately, the true issue dawned on her at 3am, and she fell asleep confident that she knew how to fix the situation.

“Sir Aat,” she addressed the commander at breakfast the next morning. “We need to discuss the attack last night.”

“Yes.” agreed the commander. “Now you see why we need the reinforcements.”

“No. I do not.” responded Ann.

The commander looked shocked. The rest of the dining hall fell silent. Everyone waited to see what Ann said next.

“What you need are better names.” Ann continued.

The commander laughed deeply. “You don't understand. We have already improved our names. When a soldier joins the outpost, they are assigned a new name. Every name is short, so that commanders can call out orders quickly in battle.”

“No. It is not.” disagreed Ann. “It is inefficient.”

“No offense Princess Ann, but what do you know about commanding in battle?” he asked.

“Only what I observed last night. But from that limited introduction, I can assure you that the names are hurting your efforts.”

“I think you are mistaken.” declared the commander. “They allow us to issue commands at incredible speeds.”

“Yes they do.” agreed Ann. “But they are prone to mistakes. Last night, you corrected yourself 89 different times. The names are too similar and thus too easy to confuse. Plex and Drex. Ut, Ot, Et, and Aat. The short names do not help!”

“Ha! What would you suggest?” scoffed the commander.

“Use descriptive names. For example, Plex should be called 'South Tower Archer' or at least 'Archer 1'. That more accurately reflects his role.”

“That is crazy!” bellowed the commander as he slammed his mug of coffee on the table. “Do you know how long it takes to say 'South Tower Archer' in the heat of battle? We would waste valuable time.”

“Do you know how long it takes to say 'Drex, swap places with Plex, we need a archer on the wall not a blacksmith.'? Any measure of efficiency needs to take into account the time spent on corrections.” countered Ann.

The commander had no response for that.

“And what about you?” Ann continued. “Why not have them call you Commander or Captain?”

“Our names already reflect rank.” replied the commander. “The names proceed down the ranks in alphabetical order. It allows any solder to instantly know who outranks them! It makes life simple!”

“No. It does not.” corrected Ann again. “In order for the solders to even refer to each other, they have to learn new made-up names. Why not have them learn the ranks instead? Either way they have to learn something new. Only, in this case, the ranks mean something.”

“But we have a good system!” argued the commander.

Ann sighed. “It is like programming a complex algorithm.” she explained. “Using very short variable names can make it feel more efficient to program, because you can type out the code faster. But, in the long run, it can do more harm than good. It becomes easy to make mistakes and difficult to sort out what is happening. Often times, slightly longer names can make a significant difference.”

The commander opened his mouth to argue, but was unable to think of a rebuttal. Instead, he sat at his table, mouth open, with a confused look on his face. After a while he spoke.

“I think you might have a point.” Secretly, the commander also felt a small pang of relief. He had never been fond of his own assigned name. He often found himself day dreaming of his solders snapping a salute and shouting “Yes Commander!” in unison. Maybe this change would not be so bad after all.

That afternoon, the commander changed every soldier's name to be longer, but more meaningful. Over the next few days, the troops stumbled through drills, getting used to their longer names. But soon, Ann began to see efficiency improve.

A week later, on Ann's final night in Garroow, there was another goblin attack. This time the invading force consisted of 10 highly trained goblin special forces troops. The Garroow soldiers turned away the attack with ease.

As Ann left the garrison, she took a small bit of pride in the dramatic improvements in the forces there. After indulging in the brief moment of happiness, she turned her horse East and continued on her quest to save the kingdom.

---------------------------

If you are interested in learning more about writing good code, check out: The Importance of Comments: A Tale of The Baker's Apprentice, The Curse of Excessive Commenting, or The Importance of Unit Testing Magic Spells.