It was a stormy afternoon somewhere in Poland. In the town center, amid heavy rain, one could see a single window with a light on. In that room was a young programmer Peter, on the verge of exhaustion. He was working on fixes for a pull request after a code review.
“What does this method do?”, “Why do we need so many parameters?”, “The purpose of this ‘let’ is unclear.” – all these questions echoed in his head. He had an obvious problem communicating with his code. Peter knew that naming was one the hardest problem of software development, yet he struggled to improve this area.
“If only I had the knowledge, secret knowledge on how to make my Swift more swifty,” he lamented. Roar! A thunder rolled over the sky, illuminating corners of the room. The young programmer gasped. He spotted a silhouette across the room, but its face was hidden in the shadows.
“Ah, if it isn’t the Senior Developer – probably waiting for fixes in the pull request,” Peter thought. “I’m working on it… just give a second…” he started with a broken voice, but the Senior stopped him.
“I can see your struggles, young Peter, and I’m here to help you,” he said. “I will share with you the 5 secrets of Swifty API design.”
The first secret: API design guidelines
“You are not alone in your troubles,” the Senior began. “Swift is a young language and as every language, it has its own way of telling stories,” he paused for a second. “Stories about problems and solutions. Many before you have been looking for its natural voice and those who’ve come the closes have created a sacred document.”
Peter instantly understood what he was describing: API design guidelines. A set of hints that provide guidance in rough seas.
“‘Clarity at the point of use’, ‘Clarity is more important than brevity’, ‘Write a documentation comment,’” the Senior continued and Peter nodded almost unnoticeably recognizing fundamental points of the document.
After a long pause, the Senior finally whispered, “The first secret is revealed.”
The second secret: Study well-known APIs
“Swift is a young language, but it has already established a core. A core that can be a beacon of light, but only if you let that light in.”
Peter was confused. “I want to let the light in, but how do I find the core?”
“Look into your code from the day before, and the day before that day,” the Senior answered softly.
Peter began to think about all the .append(contentsOf:) and .dataTask(with:, completionHandler:) he had used this week, but before he could gather all his thoughts, the Senior interrupted him with a whisper, “The second secret is revealed.”
The third secret: Ask people for feedback
“What answer will you hear when you ask someone: ‘What sound does a cat make?’” the Senior asked.
“Meow!” Peter gave an immediate response. The sound he made was so quick and loud, that despite the heavy rain outside, the cats that had been sleeping near the garbage container downstairs instantly ran away, hissing in anger.
“That’s right. Will you get a similarly quick answer for: ‘What sound does a bearshark make?’”
Peter lost himself for a moment trying to imagine the sound, but once again, the Senior broke the silence.
“If not, maybe you should not have created a bearshark in the first place?”
The young programmer noded with understanding – if fellow developers can’t figure out what your creation does only by its name, maybe you can do better than that.
The Senior put his hands together in a sign of contentment. “The third secret is revealed.”
The fourth secret: Use your APIs in tests
“It is said, that Madam Curie tested her work on herself. Her long-time exposure to radiation gave her two Nobel prizes and leukemia,” the Senior began ironically. ”This could be madness… or genius. It’s so hard to tell one from the other.”
Peter shifted his questioning eyes to the place where his interlocutor was now standing.
“You may play the mad scientist too, by being the first user of your APIs in tests,” the Senior continued.
“Should the test come before or after implementation?” Peter followed up immediately.
The Senior moved a little bit, as if ready to give an answer, but then stopped. For a moment, one could only hear raindrops hitting the window. Finally, he answered in a quiet tone, “You are not ready, but the fourth secret is revealed.”
The fifth secret: Perfectionism is your enemy
“You will always have more than a lifetime of work waiting for you in the backlog,” the Senior broke the silence after a while. “Some APIs are important, some are not. Some will be used by thousands, some will be used once.”
The young programmer turned to the window, trying to hide a single tear rolling down his chin. He recalled that one situation when an entire project was on fire, yet he spends all his time perfecting that one parameter, in that one private method, in that one helper class.
He finally spits out “How do I recognize it?”
“Prioritize relentlessly. Prioritize mercilessly.”
When Peter finally got it all together, he looked up into his reflection in the window, meeting eyes with his worst enemy. Not being aware of what he was doing exactly, he whispered to himself, “The fifth secret is revealed.”
Roar! Another thunder rolled through the sky, illuminating corners of the room. Peter turned around and his heart skipped a bit. He was alone in the room again.
Epilogue
Peter never met the mysterious person again. Who was he? A ghost? Peter’s own imagination? Chris Lattner projecting himself to the Swift developer in need? Peter never found out, but the events of that stormy afternoon stayed with him for the rest of his career. He always remembered the five secrets of the Swift API design. He regularly studied API design guidelines, standard libraries, and the Foundation. He evaluated his naming with people and with automated tests. He used priorities as a lighthouse in the sea of his work. He became a competent craftsman and went to accomplish magnificent things, but that’s a story for another time…
For more about Swift read one of our related articles:
July 31, 2018
