Impactful Refactors: Refactoring for Readability

Empathy in Programming

Kinsey Ann Durham

@durhamka

#refactoring

#developer-experience

#mentorship

#onboarding

#empathy-in-programming

#ruby-community

Impactful Refactors: Refactoring for Readability

by Kinsey Ann Durham

In the talk "Impactful Refactors: Refactoring for Readability" presented at RubyConf AU 2017 by Kinsey Ann Durham, the focus is on the importance of refactoring code to enhance readability rather than merely optimizing for performance or other technical aspects. The discussion centers around how developers spend more time reading and understanding code than writing it, making readability a critical aspect of software design.

Key points discussed include:
- Readability Over Performance: A strong argument is made that readability should be prioritized unless performance issues necessitate otherwise. Developers are encouraged to avoid 'clever code' that can obfuscate intent and understanding.
- Teachable vs. Readable Code: The distinction between teachable code (simplified for learning) and readable code (which communicates its intent) is explained. While teachable code can help new developers, it should not form the basis of production code.
- Naming Conventions: Emphasis on the importance of clear, descriptive naming for variables, as this enhances understanding and communicability of the codebase. Long, clear names are preferable to abbreviations.
- Refactoring Examples: Real-world examples are provided illustrating how refactoring can lead to better design. One example involved breaking down a complex 300-line Backbone view into smaller, more manageable classes, resulting in improved readability and ease of understanding.
- Cultivating a Culture of Readability: Suggestions for fostering an environment that values code readability are discussed, including pair programming, code reviews focused on readability, and encouraging developers to leave code in a better state than they found it.
- Humane Development: The importance of creating code that is accessible and understandable by all developers, especially new ones, is highlighted. This promotes inclusivity and better onboarding processes.

In conclusion, the talk advocates for the principle that readable code not only enhances productivity and team dynamics but also benefits the onboarding experience for new developers. By investing in code readability, development teams can facilitate a smoother transition for junior developers and ultimately improve the quality of their work. The message reiterated is that readability should guide development practices, emphasizing that software is primarily for human users and developers rather than machines.

00:00:09.280 Hi, is everyone having a good time? Yeah? Awesome! I'm going to skip this slide because I just got an awesome introduction, which isn’t usual. Thank you! I work at a company in Denver called Go Spot Check, and I also mentor students how to code all around the world through a program called Block in my free time. That’s super fun when I'm not fly fishing or spending time outside.

00:00:15.440 Today, I'm going to talk about refactoring. It's a big part of what we do as developers. While technically it's not a refactor, performance optimizations are a common activity. We also refactor to implement design patterns or to improve our code in some way. But what if I told you that there is a type of refactoring that could be even more impactful and meaningful? I believe that refactoring to make code more readable is essential. Good design means more readable code. Yet, I acknowledge that there are times where readability may get overshadowed by other considerations. For example, we are currently dealing with scaling issues at Go Spot Check, and sometimes we need to do whatever it takes to keep our app running. Often, that means writing ugly, unreadable code. I argue that you should save that as a last resort. Readability should always trump performance unless absolutely necessary. Many times, performance optimizations can deteriorate readability.

00:01:01.760 This is a graph from Jeff Atwood's blog—I'm sure some of you know him. He argues that from his perspective, we spend significantly more time trying to understand code than doing anything else, so I think readability is crucial. Additionally, Nat Pryce and Steve Freeman state that developers spend far more time reading code than writing it, so that's what we should optimize for. A fantastic book to check out on this topic is 'Growing Object-Oriented Software Guided by Tests.' Michael Feathers also mentions that readability is the best default or the most important aspect of nearly all code. Today, we're going to discuss teachable versus readable code, go through some quick examples, talk about components, and then dive into the how and why of these concepts.

00:01:49.399 First, let’s start with teachable versus readable code. In previous versions of this talk, I approached this issue by almost 'dumbing down' the code or simplifying it to make it more readable for junior developers. However, my mentor and co-worker, Kim Barnes, taught me that what I was referring to was something called 'teachable code.' Teachable code should not be the norm for production. I want to clarify that making code more readable is not the same as dumbing it down. Readable code truly means better-designed code. In an article I really loved, Peter Jen explains that readable code clearly communicates its intention to the reader. On the other hand, teachable code makes the specific concept being taught as explicit as possible.

00:02:58.800 Concepts related to teachable code are important because they can significantly help junior developers in your organization level up. Kim helped me grow a lot quicker by focusing on this. However, it’s essential to ensure that you then revert to the production code after using teachable code. You don’t want teachable code in production, as it can do a disservice to your codebase and other developers on your team. I want to quickly go through two examples of readable versus teachable code. In the first example, we have readable code or code that you would have in production—it's a succinct and readable way to find our dogs. In contrast, teachable code could look more verbose, breaking it up into multiple lines and explicitly detailing how we are finding the dogs. Another example involves taking a single large class or method and breaking it down; readable production code consists of small methods that are well-named and each have their own responsibilities, while teachable code might combine all these methods into one for clarity.

00:04:30.800 It’s critical to slow down and take small steps when explaining these concepts using teachable code to juniors. I want to emphasize again that readable code is not the same as teachable code. Now we’ll look at more examples focused on readability. Firstly, let's talk about naming. There’s a popular blog discussing presenters in Rails, where it shows the creation of an instance variable called 'post.' However, post is referencing a new instance of post presenter. Why not name this instance variable 'post presenter' so that it’s immediately clear that you can call methods from the presenter class instead of the post class? Additionally, don’t fear long names. People often abbreviate or use single words when a longer name could provide much more clarity. A variable's name serves as a comment, and you should take advantage of that.

00:05:44.400 John, who’s taking pictures here, told me that writing good test descriptions is also very important. Describe what you’re testing; it makes everyone’s lives much easier. Stick to the standards—recently I came across some code in my codebase that lacked vertical spacing, which bothers me. Our team has a standard of using spaces, and our industry also follows that, so use it. I see neglecting this as laziness, which ultimately affects readability. So, my biggest piece of advice for making your code readable is to stop writing clever code. Justin Cal gave a great talk at RailsConf about this. Clever code doesn't impress; it can make others feel stupid. Reserve showing off clever code for side projects. Don’t sacrifice the readability of your code to showcase something new you learned.

00:06:28.000 Be courageous and write boring code. The goal should not be to minimize lines of code but to minimize the time needed to understand it. Next, let's discuss longer-term refactors that you can do to enhance code readability. Chad Fer states that if your services are so small that you can read them in one go, you probably don’t need a test. I may not fully agree with that because I write tests before code, but I appreciate the idea of readability. Break things into the smallest possible components to design better code, making it more readable. It will also enable you to keep context in your head rather than feeling overwhelmed by too much cognitive load. Importantly, name these objects clearly so that their responsibilities are transparent from the outset.

00:08:40.960 Though this is a Ruby conference, I want to illustrate that similar concepts apply to JavaScript. I had a recent refactor in a JavaScript service designed well from the get-go. Recently, I needed to fix a bug in a Backbone view that was over 300 lines long with very few tests; this is just the top half of the file. It took me a long time—about half a day—to understand what this view was doing. These large classes and views can be intimidating for any developer. My partner and I decided not only to fix the bug but also to refactor this class to improve its readability and design. We chose to follow a test-driven approach.

00:10:43.760 As we started pulling things out into smaller plain old JavaScript objects (POJOs), it became easier to comprehend the functionality. Initially, we thought it would be challenging to test this. Using Jasmine as our testing framework, the more we broke things apart, the simpler testing became. We began by creating a filter processor factory that returned a new instance of the type of processor needed. Subsequently, we separated each filter into its own processor class, making its processing clearer. Gradually, the 300-line Backbone view shrank, revealing its function more transparently. Not only did it become more readable, but we also discovered we could extract a base class for all processors, reducing the original Backbone view’s code significantly.

00:12:30.000 We even removed many comments since the code became self-explanatory. Remember that excessive comments often indicate that the code isn't readable, which can be a code smell. Once we understood the situation, the refactor took only a day. I initially feared it would take much longer, but I’m glad we took the time to refactor and test drive our code rather than just fixing the bug and leaving it. In this case, we ended up with fully test-driven code, a resolved bug, and a more readable and extendable codebase. We created tiny, flexible components that we could reuse later.

00:14:22.799 Examples of these refactors really reinforce that truly readable code results in good design. This concept isn't new; most of you have probably encountered it, but you rarely receive advice from someone who isn't a senior developer. Now, let's discuss how we can improve our code readability. Raising awareness about this within your team is essential. Always keep this in mind when writing code. Pair programming can be advantageous; having another set of eyes can help identify clever code that may be more complex than necessary. Additionally, taking breaks allows you to revisit your code with a fresh perspective. Code reviews should emphasize readability, whether during team reviews or pull request evaluations. Always strive to leave the code in a better state than you found it.

00:16:06.999 It's easy to fix a bug and move on, but I truly believe it’s worthwhile to invest the time for refactoring. Building code readability and good design should be foundational pillars in your engineering organization. Embrace the importance of readability—not only does it enhance productivity for everyone involved, but it also facilitates better onboarding for new developers. When the code is understandable, it drastically reduces their initial learning curve.

00:17:03.840 We are ultimately developing software for humans, benefiting human users. Ernie Miller introduced the term 'Humane Development,' emphasizing our work extends beyond just writing code for machines. We should focus on creating code that our teammates can easily comprehend and work with. The Ruby Community continues to grow in diversity, with many new developers transitioning from various backgrounds. This inclusivity necessitates crafting accessible code. Companies sometimes overlook their code quality when onboarding junior developers, leading to a toxic culture. I believe that the readability of your codebase can significantly impact how well you onboard and nurture junior developers. Writing readable code is vital not just for mentoring but for the overall quality of our work. As we wrap up, remember that readability should be the core principle guiding our development practices.

00:18:16.170 Thank you!

RubyConf AU 2017