Micro Talk: Impactful Refactors - Refactoring for Readability

by Kinsey Ann Durham

In the talk 'Impactful Refactors: Refactoring for Readability,' Kinsey Ann Durham emphasizes the importance of code readability and its impact on developer onboarding and overall team productivity. As a software engineer, she shares insights from her experience and highlights that while performance can sometimes take precedence, prioritizing readability leads to significant long-term benefits. The presentation includes these key points:

Importance of Readability: Durham underscores that readability is crucial for understanding and maintaining code. Readable code enables faster onboarding of new developers and boosts productivity across teams.
Improving Naming Conventions: She provides examples of poor naming conventions that hinder understanding, such as using ambiguous names like 'post' instead of 'post_presenter,' which clarifies the variable’s purpose.
Avoiding Cleverness: The speaker advises against writing 'clever' code that sacrifices clarity for the sake of brevity or innovative techniques, suggesting that developers should focus on code that communicates its function clearly.
Enhancing Code Communication: Through practical examples, such as naming a method 'birthdateasinteger' instead of just 'birthdate,' she illustrates how naming can function as indirect documentation, improving readability and understanding.
Empathy in Development: Durham advocates for empathy-driven practices in coding, suggesting that developers should consider the diverse backgrounds and skill levels of all team members when writing code. This aligns with the humane-driven development approach, emphasizing that code should be accessible and inclusive.
Resources for Improvement: She recommends studying works like 'Puter' by Sandy Metz and 'The Art of Readable Code' to learn further readability techniques.

Conclusively, Durham asserts that making code readable is not just about personal preference; it fosters a collaborative environment and encourages a culture of inclusiveness in teams. By writing clear and accessible code, teams can better support junior developers and continue improving their overall coding practices.

00:00:15.520 Hello, I'm Kinsey Ann Durham, and today I'm going to talk about impactful refactors. I'm a software engineer at Go Spot Check in Denver, Colorado. In this talk, I'll go through a couple of examples and discuss the underlying reasons for these refactors.

00:00:20.840 Before I jump in, I want to clarify that while I will focus on readability, I understand that there are times when readability may be overshadowed by other priorities. For instance, my company is currently dealing with scaling and performance issues as we grow. In such cases, we often need to make decisions that keep our app running, even if that means using code that is less clear or readable. It's crucial to save unreadable performant code as a last resort or only use it when absolutely necessary.

00:00:46.879 I often see people write highly performant code that is unintelligible even when there are no performance issues present. As a disclaimer, I am coming at this from a non-technical background; I wrote my first line of code four years ago at a RailsBridge workshop and did not attend a coding school or earn a CS degree. In college, I studied advertising. For me, making code readable significantly boosts my productivity. Coming from a different background, readability gives me the confidence to persevere, as programming can be challenging.

00:01:15.470 When I can read the code and contribute, it makes a huge difference. It helps combat feelings of impostor syndrome and also improves productivity for everyone else on my team. To quote Michael Feathers, he states that readability is the most important aspect of nearly all code. I want to share a couple of examples of situations where I had to debug unnecessarily due to poor naming conventions.

00:01:56.749 One example comes from a popular blog about presenters in Rails, where an instance of the PostPresenter was created and referred to simply as "post." Why not name the instance variable "post_presenter"? This way, I immediately know that I can only call methods from the presenter class and not the post class, avoiding a hunt for where the instance was created.

00:02:59.800 There are instances where including type and unit information in your names can be beneficial, though I know this is a controversial topic. I don't suggest applying this universally, but only where it adds value and to use it sparingly, as it can become cumbersome to maintain. For example, a method called "birth_date" returns an integer that represents epoch time rather than an actual date—something that isn’t clear from the name. It would be better to rename it "birth_date_as_integer" to communicate that detail up front.

00:03:41.350 A variable's name can function as a comment, providing clarity in understanding the code. For example, if I have an instance variable named "agility_cattle_dog_with_a_wheat_allergy," while it may seem excessive, it communicates the necessary information. Although this may lead to longer variable names, the trade-off is justified in terms of clarity and understanding.

00:04:23.950 Another readability concern is the practice of abbreviating names, which often differentiates junior developers from senior ones. For instance, using a block argument abbreviated as "d" for dog is less readable than spelling it out as "dog." I've heard critics say this is a distinction between junior and senior developers, where seniors tend to think more abstractly and utilize methods like map or select. However, this can sacrifice maintainability as it introduces cognitive overhead when thinking about the loop.

00:05:35.840 I believe this is a crucial consideration: Should we trade off maintainability for the sake of junior developers? I don't have all the answers, but these discussions are vital within our teams. One crucial piece of advice I offer for writing readable code is to stop writing clever code. While it's tempting to showcase new tricks or innovations, one should reserve these for side projects.

00:06:04.159 The objective should not be to minimize lines of code; rather, we should aim to minimize the time it takes to understand what the code does. There are numerous practices to enhance readability, like establishing explicit interfaces and employing small helper methods with descriptive names. For a deeper understanding of these principles, I recommend books such as "Puter" by Sandy Metz or "The Art of Readable Code." These resources provide plenty of examples of readability practices you can apply daily.

00:06:37.950 Now, I want to delve into the reason why writing readable code is critical. Readable code is easier to change and maintain because I can quickly understand its function and don't spend unnecessary time debugging. It also ties into best practices, as the principles found in Sandy Metz's "Puter" promote not only good object-oriented design but also enhanced readability. Engineering teams can collaborate more effectively when the code is clear, enabling remote work without the constant need to interrupt coworkers for clarification.

00:07:34.300 Onboarding is another important aspect—not just for junior developers, but for everyone. High readability facilitates a smoother onboarding process, making it easier for new developers to acclimate to the codebase. As Nadia mentioned earlier, it’s important to create an approachable and welcoming environment for people diving into your code.

00:08:30.730 Moreover, the concept of humane-driven development, as coined by Ernie Miller, emphasizes that we are humans creating software for the benefit of other humans. Our focus should be on producing code that our teammates can understand, particularly as our community grows increasingly diverse.

00:09:05.750 As more individuals from different backgrounds start coding, it's essential to create a culture of inclusiveness. We should strive to write code that supports this diversity by keeping it as readable as possible. Many new developers today lack extensive coding experience, making it even more crucial to craft code that can be easily understood. If companies intend to hire junior developers or have juniors on their teams, they should invest the time to refactor for readability, providing an environment where those developers can thrive.

00:10:00.130 Keep in mind that it’s important to consider readability as a priority before bringing in junior developers. It’s about empathy—putting yourselves in the shoes of those who will read and maintain the code. Think back to your early days of learning to code and how challenging it was, regardless of the language.

00:10:39.520 Ultimately, whether you envision hiring juniors or sticking to a solo venture, ensure that your code remains accessible and readable. Remember that Ruby, as a language, was designed to be enjoyable and readable. Let's hold on to and reinforce this ideal, continuing to promote empathy and clarity in our coding practices.

00:11:00.230 In closing, I encourage you to always question your code, push yourselves for improvement, and advocate for empathy and diversity in our Ruby community. Keep your code readable. Thank you!