How to write readable code

Community Tips and Resources
#1

I found this guide on how to write more readable code quite helpful.

“Readability” of code is a pretty amorphous term. I’m not sure where to find any generally accepted principles for what makes code more readable, what makes code readable for different programming languages or programming paradigms, and what types of things have to be sacrificed to increase code readability, and when they are worth it or not worth it.

Do you folks have some good non-book resources on how to write more readable code? I’m looking for general principles, but ones which apply to Python and web development are especially helpful, since that is what I am learning.

Thank you!

1 Like
#2

You can look for style guides of big companies to get an idea of how they approach certain languages (styleguide | Style guides for Google-originated open-source projects).

Pep8 is the big general one for python: PEP 8 -- Style Guide for Python Code | Python.org

2 Likes
#3

Or if you’re musically inclined: 🎵 The PEP 8 Song 🎵 - YouTube

(courtesy of @el_cocodrilo)

5 Likes
#4

I am a little curious as to why not books? Even if you don’t get a physical copy, the layout of books is designed for something like this and if nothing else having a series of examples tends to help a great deal.

For python specifically I think it’s worth looking into some of the tools that automate parts of this for you, linting tools like pylint, flake8 (mypy for type checking) and such will do basic code analysis and check for a number of common issues, both actual errors and silly things like unused variables or excess whitespace.

A further option would be the automatic formatting tools like yapf, autopep8 and black which will format entire files/directories for you. Having a look at the output of such formatting options will show you at least what a fair few people think is readable. That’s a good jumping off point at the very least should you find a spot where you think it’s better to break from convention. These aren’t the only linting/formatting tools so have a shop around if you like.

1 Like
#5

I’ve never seen that before and I absolutely love it! :heart: :heart:

#6

Should be the national anthem of the python section of the forums.

#7

It should! That’s amazing!

#8

Thank you for your answers! I learned about some important tools and resources I wasn’t aware of.

I suppose my question was a bit unclear, which makes my point about “readability” being a vague term.

I was asking about readability with regards to structuring code, not formatting it. That is how I understood the term “readability” when applied to code. Is that… not how it’s generally used? Is it really mostly talking about formatting, not the chosen tools or logic of any given line or block of code?

The guide that I posted does not talk about formatting and style at all, only structuring code for improved readability.

#9

Not books only due to length: I’m a beginner and I’m just looking for a very basic idea of these concepts right now, as I want to spend time on other things. So I want something concise.

In general I love books! I just don’t have time to read a book on every topic I need to learn about!

#10

I think there are simply multiple aspect to readability of code, indention certainly being one of them.

also very important. Lets say I have complex piece of code, for example to reverse a string. If we then have function which implements this reverse, then the function call looks like this:

reverse("hello world")

we now know that we will get: “dlrow olleh”. The string has been reversed. We don’t need to understand the underlying implementation. But by given the function a logic name, we know what happens

by making a function, we can give the function a logic name, making it clear what is happening. Making the code very easy to read and understand

now lets compare this with:

"hello world"[::-1]

do you instantly know what happens? The string is also reversed, but was it just as easy to read? Of course complex pieces of code/logic are sometimes inevitable. Then the challenge is to make the code easy to understand what the code is suppose to do

by having a function (besides being easier to understand), we also have a more re-usable piece of code.

1 Like
#11

Thank you for addressing one of the questions I had about readability, which was about when, besides re-usability, to tuck away even a small number of lines of code into a function. The single-line [::-1] example makes that very clear.

Relatedly: If I know how to compress several lines of code into one longer line of code, is that better or worse for readability? For example, a list comprehension, especially a more complex one, perhaps one that uses nested for loops, is not as “readable” as writing it out as a for loop(s). So is there ever a time when it’s better to write out the for loop instead of just using a list comprehension?

#12

This was just one example. Sometimes your function will obviously contain multiple lines

there isn’t a fixed rule, but if you have nested ternary operator or nested list comprehension, that is not very readable. Then you are better of using loops or functions to make your code more readable

1 Like