Python Guy

Python Sucks (… when you suck at writing code) August 26, 2011

One of the neat features of Python is how readable it is. For most of your code, you won’t have to document what the code means, just why you chose to do things a certain way.

I am poking at a long function, more than my 1080p rotated monitor can fit on one screen at a readable font size for me. It flows off the edge of the screen, making it hard to see how different pieced fit together.

I don’t like long functions. When you reach a certain number of variables in a particular scope, or when you have bits and pieces of your code spread out like peanut butter, it becomes unreadable.

Of course, long functions are probably better than the alternatives, provided you can’t separate out different parts of it.

The author of the code I am reading decided it wasn’t a good idea to put relevant pieces of code together. As a result, the code is intertwined.

Variables are created in one spot and used in another. In between, they are not relevant at all.

  the_var = the_value

  ... some irrelevant bits of code ...

  use(the_var)

Obviously, it is much more readable if you do things this way:

  ... irrelevant bits of code ...

  the_var = the_value
  use(the_var)

  ... other irrelevant bits of code ...

Or even better, eliminate the variable altogether:

   use(the_value)

By minimizing the mixing of code, it becomes much easier to read the code and put things together in my head. This is no different than writing English in paragraphs, where each paragraph has sentences that relate to each other.

In addition, you can make your code more readable by sensibly keeping the variable count down. Sometimes, reducing the number of variables means you have a more complicated expression, so you have to think carefully about how to do this.

Comments, in addition to vertical whitespace, can be used to separate “paragraphs” of code. I use single-line comments when I’m talking about the next few lines, but multi-line comments when I’m talking about entire sections of code.

#
# This is a description of the following block of
# code. Note how it sticks out because of the white space.
#

# This is a comment about the next two lines of code.
do_something()
while you_do_something_else():
   append_this_to_that()

# This comment applies to the next few lines.
this = that + that_other_thing - 5
these = [that, that_other_thing]

I hope my point is clear. You can write wonderful code, but make it entirely illegible, even in Python. So don’t do that. Take a little bit of time to make your code readable. Your future self will thank you.