How to tell a better story (in code)(final)
- 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!