To tell a better story in code, start with knowing your audience, use ubiquitous languages in your code so that no translation is needed for your audience. Apply visual design principles to identify code smells and organize the layout in a way to strengthen the communication. Start from there then practice often by refactoring. The truth is there are never shortcuts to tell a better story in life or in code, practice practice practice by refactoring we will make our code tell a better story. Let’s opt in better software for our future selves and others. Let’s make our code accessible for those who are interested in our code. Let’s invite our audience to our story in code.

1. How to Tell
A Better Story
(In Code)

2. Welcome to NYC
Welcome to NYC.
This is my first ever conference speaking. Start with the Call For
Proposal day event in Feb organized by Write/Speak/Code,
Google developer group and Codebar. During that event we
promised that we would at least submit one CFP by the end of
this year, and here I am. Everyone please raise your hand. Can
you promise you would also submit at least 1 CFP this year? Yes
you do. We saw it. Thank you!!

3. Who Am I?
• Bonnie Pan
• Staff Applications Engineer
• Medidata Solutions
My name is Bonnie Pan.
I am a Staff Applications Engineer at Medidata Solutions. We
develop applications for clinical trials, making an impact in
patients’ lives around the world.
I am an immigrant from China. I moved here 11 years ago and
started my family here.
I am very proud to be a mom of two kids. I spend a lot of time
with them trying to teach them about the world. my favorite
method to teach is telling stories.

4. The 3 Story Rules
Storytelling is hard. After years’ practice I have learned some
rules to tell a better story.
I find these rules can apply to coding as well.
So… what are the rules that I apply for a good story?

5. RULE #1
Know Your Audience
Rule #1: Know your audience.
While this is more obvious with my children, it is not obvious with
Code.
So the first question is, Who is the audience of our code?
Who reads our code; who modifies our code;who wants to know
the logic behind the code;how to make sure that those who
maintain the code and who consume the code are on the same
page?
It is better to know these before we write the code.

6. “To communicate effectively, the code must be
based on the same language used to write the
requirements - the same language that the
developers speak with each other and with
domain experts.”
–Eric Evans, Domain Driven Design
I recently switched to a new development team in the same
company.
I noticed that we were calling the same concept of a business
entity that performs clinical trials differently on different teams,
one team referred to it as study group, while the other called it
client division. When we collaborate on integration, we need to do
this translation all the time. This is a cognitive cost that we want
to prevent.
One technique to keep us aligned is to speak and code in
Ubiquitous Language.
Ubiquitous Language is a term that Eric Evans uses in the book
Domain Driven Design for the practice of building up a common
and rigorous language throughout the team.

7. Speak in Ubiquitous Language
It is a language understood and spoken by everyone on the team
and in all communications.
To cultivate ubiquitous language is to model it loud and use it in
all communications including code. When in conversations with
product, testers and developers, come up with terms to describe
the business concepts, and pay attention to those specific terms
that the team agrees on. Then use those terms in the code.
Ubiquitous language represents the intersection of business
jargon and technical jargon. We can still use the implementation
oriented technical terms among developers, however the core
concepts in the domain should not allow synonyms or
translations.

8. Code and people have a bidirectional relationship.
It is obvious to see how people can impact code. Because it is
people who write and modify the code. But existing code also
impacts people. For example I would automatically pick up terms
in code for discussions. I would copy the existing code patterns
as a team convention.
When we code in the ubiquitous language we preserve and
accumulate the abstractions and the knowledge of the domain.
Ubiquitous language is essentially a domain model based
language, as we refine our language, the domain model also gets
richer. It connects team communication to the software
implementation. Therefore, no translation is needed within the
team.
Because the language is based on the domain model, when we
recognize a change in the language, it also indicates a change is
Code in Ubiquitous Language
Code <——-> People

9. needed in the domain model, which resides in the code. Therefore,
speak and code in ubiquitous language requires a conscious team
effort and commitment to exercise the language.

10. Utilize other asynchronous
communication artifacts
• Scenarios
• Tests
• Commits
• Pull Request
Descriptions
• Documentation
• Coding Decisions
What I learned from my storytelling experience to my kids, is that
reading the words out loud in a colorful story book is not enough
to attract their attention. I find I often need to sing, ask them
questions, or play games with my kids while telling them stories.
Same applies to the code. What needs to be there for whoever is
interested in our code?
How do we write the code so that our code is more accessible to
our audience?
For product, it is helpful for them to see scenarios that are written
in english and describe high level business workflows.
For testers, it will be helpful for them to review scenarios and test
cases. I have worked with testers looking for information in pull
requests and each commit messages along with them. So it is
good practice to write a short paragraph on the background
context of the code changes, and write more descriptive commit

11. messages.
For developers, start with intention revealing names for parameters,
variables, methods, classes, and file names. I find it is also helpful to
note down some coding decisions of why we write code in certain
ways. Own your expertise in writing!
For technical writers, they will love us if we add diagrams and
up-to-date documentation.

12. But How to Write it?
We have discussed how to tell a better story in Code, the first
step is that we need to know our audience, speak and code in
ubiquitous language, and utilize other communication artifacts to
invite our audience to our code story. But how to write it? Let’s
write some code together next.

13. Let’s Code FizzBuzz!
Let’s code FizzBuzz!
I found this FizzBuzz game online. The game is to play maths with
kids. I am going to save this game for Aimee when she grows up.
It is to practice 5 and 7 times tables.
On the left side is the text description of the game. On the right
side is examples.
The rules in this game are..
How about when a number contains multiple 5s for example 55?
Should the player say Fizz Fizz or Fizz Fizz Fizz?
This is why examples are important in requirements because
description in text often have ambiguities. We use examples to
remove ambiguity, clarify requirements, and make sure we are on
the same story.

14. Since today I am talking about how to write a better story in code.
I thought it would be helpful to start with some story in code and
to make it better along the talk.
The code is in ruby. But the concept is language agnostic.
In fact I switched from C# to ruby last year due to the change of
teams. So my code may not look very ruby idiomatic.
Ask yourself if you can tell the rules of FizzBuzz by taking a
glance of it.

15. Considering what we have discussed, I added tests, utilize other
communication artifacts to compliment our story in code.
Tests are very important.
First of all, they are live requirement documentation. And more
than that, good tests identify and remove ambiguities in the
business requirements.
Secondly, well covered test cases serve as a safety net for future
code changes.
The last thing we want to do in refactoring legacy systems is to
change the existing behavior.
So before we start changing code in a legacy system without
tests, we write tests first. We call those tests capturing the actual
behavior of a piece of code “Characterization tests”. We continue
adding tests until we are satisfied that we understand the code.
Now that tests are available, let’s make the code easier to
understand. Where do we start?

16. We start with code smells. I drew this picture.
A code smell is any characteristic in the source code of a program
that possibly indicates a deeper problem. This is a well explored
area where we have tools available to help us identify those
smells such as data clump, long method and conditional
complexity. For example, we can use the rubycritic gem to identify
ruby code smells.
Human beings are naturally good at visual processing...
Does the visual presentation of the code convey additional
information?
If we borrow the visual design principles from the publishing
industry, will they help us identify code smells and thus improve
the code?
Code Smells
What are they?

17. RULE #2
Visual Design
This comes to my Rule #2 Pay attention to the visual and use
visual design principles to identify code smells and make the key
information stand out.
The Visual design principles we will talk about today I am sure
you already use some of them automatically. I would like to talk
about these small things so after the talk we can do it more
consciously and thus with more strength. Focus on these visual
design principles and think about what they can do for
communication.

18. Look at this version of the code for FizzBuzz problem, the
fizz_buzzify method is too crowded.
It is lacking empty space so my brain immediately shuts down
when I see it.
A lot of lines of code without spacing is the first code smell to me.

19. Visual Design
Principle 1:
White Space
White space in visual design is empty space where to rest our
eyes; in code it is where to rest our brain.
My brain is small, so to me the more white space, the better,
which implies small classes that do one thing and small methods
that do one thing.
After inserting 2 lines of whitespace, I feel much better reading
the code because the white space has delivered an additional
message to me. It tells me how I can read the code in a divide
and conquer maner.
This method has three portions to it. First, a variable assignment.
Then business logic that I don’t want to read. Lastly, a conditional
logic to derive the return value.

20. Visual Design
Principle 1:
White Space
Every line of white space matters more than we would think. How about
adding one more line of white space in the second portion?
This instantly tells me that the body of the business logic contains two parts.
One is about Fizz and the other is about Buzz.
But now the code separated by the white spaces is not on the same
abstraction level.

21. Visual Design
Principle 2:
Proximity
Let’s extract the code to methods. And this is where Proximity
principle is in the play.
The Principle of Proximity states: Group related items together.
Move them physically close to each other, so the related items are
seen as one cohesive group rather than a bunch of unrelated bits.
The closeness or lack of closeness indicates the relationship.
The purpose of proximity is to organize so that the layout
strengthens the communication.
When we write code, we know which pieces of information are
logically connected, express that information graphically by
closeness. For example, a variable should be declared as close
as possible to its first usage. If one function calls another, they
should be close. Don’t put variable declaration or assignment
anywhere just because there is space and let our code readers’
eyes hop around.

22. If there are too many separate elements on a page, try extracting code
to methods to reveal a higher-level abstraction.
Watch for elements that have inappropriate relationships. If they are not
related, move them apart! This usually happens when we extract code to
methods with wrong abstraction.
Now if I take a close look at fizzify and buzzify, both of which contain two
operations. I am not certain if these two operations are related to each
other. Let’s revert by inlining the methods, and align them so that it is
easier to compare.

23. Visual Design
Principle 3:
Alignment
Now let’s inline the extracted methods back, and align them so
that it is easier to see the sameness and difference.
The Principle of Alignment states: Nothing should be placed
arbitrarily on the page.
In fact newspaper design has already told us we like vertical
alignment very much.
With the new arrangement of the code, I find the first two sections
of the business logic are about the divisible rule with different
inputs, and the next two sections are about the contains rule with
different inputs.
Wow divisible and contains! These words appear in our text
description too.
Now as I have revealed the domain concepts of divisible rule and
contains rule, I am planning to abstract to domain objects and use
ubiquitous language in code.

24. It is time to practice our idea! As the old saying goes, practice
makes perfect.
My rule #3 to tell a better story in code is to practice by
refactoring.
Refactoring is the process of changing a software system in such
a way that it does not alter the external behavior of the code yet
improves its internal structure, where a better story is told.
It is easier to read, easier to understand and easier to change.
RULE #3
Practice by Refactoring

25. Let’s review what we have done so far.
We are guided by visual design principles and have rearranged
our code so it is easier to compare.
1. Rearrange the
code
Comparing

26. Since the code is vertically aligned, it is easier to identify two
operations about divisible rule with different inputs, and two
operations about the contains rule with different inputs. We can
extract to methods and give them intention revealing name.
2. Extract to
Methods
Naming

27. Then we abstract to domain concepts and use ubiquitous
language of DivisibleRule and ContainsRule.
3. Abstract to
Objects
Domain Concepts

28. Now the code looks like this. Can you now tell the rules of the FizzBuzz
game? But what about the concept of multiple divisibles and contains?

29. The best part of refactoring is that it is an inexpensive learning experience.
We can always stash and redo it again.
As a good story is rewritten many times. I just learned on Wednesday that
Sandi Metz rewrote her first chapter 8 times. A better story in code is told
when we refactor multiple times too.
Practice another idea and compare, choose the version that helps you
understand the code better.
4. Stash and
Redo again
And continue

30. From my experience with refactoring...
• It is okay that I don’t know where I
am going

31. But believe in small but safe steps.
Start with small little things, such as rearranging the code.
Identify some code smells, give intention revealing names,
extract methods and start from there.
Baby steps, one change at a time.
By safe, I mean we create a safety net before refactoring,
which is tests.
• It is okay that I don’t know where I
am going
• Believe in small but safe steps

32. Tests are important not only they are our safety net, they also
serve as live documentation that can show us the examples
to clarify the expected behavior.
Naming is too important to ignore. Naming anchors the
understanding. hard to understand names makes us afraid to
change.
• It is okay that I don’t know where I
am going
• Believe in small but safe steps
• Naming and tests are important

33. After each refactoring, let’s ask ourselves: do I understand
the code better?
To choose between different refactoring versions: which
version do I understand the code better?
• It is okay that I don’t know where I
am going
• Believe in small but safe steps
• Naming and tests are important
• “Do I understand it better?”

34. In summary…
To tell a better story in code, start with knowing your audience,
use ubiquitous languages in your code so that no translation is
needed for your audience.
Apply visual design principles to identify code smells and organize
the layout in a way to strengthen the communication.
Start from there then practice often by refactoring.
The truth is there are never shortcuts to tell a better story in life or
in code, practice practice practice by refactoring we will make our
code tell a better story.
Let’s opt in better software for our future selves and others. Let’s
make our code accessible for those who are interested in our
code. Let’s invite our audience to our story in code.
Summary
1. Know Your Audience
- Use Ubiquitous language in Your Code
2. Apply Visual Design Principles
- Identify Code Smells
3. Practice Often
- Refactor Refactor Refactor

35. Books
These are the books which gave me ideas for this talk.

36. And Everything ever written by Dr Seuss!

37. If you are interested in my talk, please check out these talks that inspired me.
Links and References
• Ubiquitous Language Image
• https://www.infoq.com/articles/ddd-contextmapping
• Fizz-Buzz Game
• http://www.dr-mikes-math-games-for-kids.com/fizz-buzz.html
• Source code: https://github.com/bpan02/fizzbuzz
• Talks that inspired me
• Succession: A Refactoring Story by Katrina Owen
• All the Little Things by Sandi Metz
• Livable Code by Sarah Mei

38. Thank You
Bonnie Pan @bonniepan02
We’re hiring!