Readability Counts

During this talk we’ll learn a number of techniques for refactoring code to improve readability and maintainability. We’ll end with a checklist for improving the readability of your own code.

If you’ve ever found unreadable PEP8-compliant code and wondered how to fix it, this talk is for you.

Long-lived code must be maintainable and readability is a prerequisite of maintainability. It’s easier to identify unreadable code than it is to create readable code.

Let’s talk about how to create readable code.

During this talk we’ll discuss:

• whitespace
• self-documenting code
• modularity
• expectation management

We’ll conclude this talk with a checklist of questions you can use to make your own code more readable.

Outline:

• Intro (5 minutes)
  • Readability is a prerequisite for maintainability
  • Source code is made for human consumption.
• Embrace whitespace (5 minutes)
  • Well-designed typography has plenty of whitespace
  • Well-designed code should also have plenty of whitespace
  • Multi-line list comprehensions
  • Verbose regular expressions
• Names matter (5 minutes)
  • If a concept is important, it needs a name
  • Names give you something to communicate about
  • if you find yourself using a comment you might need to:
    • rename a variable to make it more descriptive
    • bundle up some code into a function or composite variable so that you can name it
• Set expectations (5 minutes)
  • show a while loop blurred out then show a for loop blurred out
  • show a for loop (blurred out) and show a list comprehension (blurred out)… what do you expect these two to do?
  • list comprehensions have a more specific purpose than for loops
  • Be specific. Intent matters. Counter counts things… I can tell by the name. List comprehensions transform one list to another. That’s specific.
  • Explicit is better than implicit… explicit code conveys intent more clearly. Implicit code leaves the user assuming.
• Mind your constructs (5 minutes)
  • map/filter vs. list comprehension
  • classes vs. functions
  • operator overloading vs. custom stuff
  • person writing the code, person reading the code, person writing code that calls your code
• Readability cheat sheet (2 minutes)
  • Is there a way you could space out this code to make it more clear?
  • Is there an opportunity to use a more descriptive name or an opportunity to give a name to a previously unnamed thing?
  • Is there a different programming construct you could use that might make your intent more clear?

Code style is my passion. I’ve learned my own code style practices from through constructive criticism on pull requests to Python and Django projects. I authored a language-agnostic code linter called EditorConfig and I’ve contributed to the pycodestyle Python linter tool.

I’ve given this talk at DjangoCon 2016, PyCaribbean 2017, and PyCon 2017.

Slides: http://treyhunner.com/readability-counts

Video: https://www.youtube.com/watch?v=NvkC5UBJqeY