Discussion – Python Readability

Readability > purity, and sometimes, even practicality. I have a pretty bad memory. When it comes to code it lasts about 2 months (when I’m lucky). This means that if I write a module in June, by September I can’t tell you how the module works, just what it does.

I love writing code. I hate reading code. I had a mentor tell me once that it takes 100% of your brain to write a module, but that reading that module is much harder. He was right. He was so right, in fact, that reading code for me is almost an exercise in futility. I curse at the person who wrote it. I hate reading code.

I have to take steps to make sure I CAN read code. For years I didn’t care about readability and I paid the price in frustrations. One fine day, after I had written a particularly difficult module (for me, at the time), I tried reading it as if I had encountered it for the first time. I started making changes, simple changes, to make it easier to read.

About 4 months later, I had to fix a bug on it. I opened it and I was able to read it!

Now, I go out of my way to make my code as readable as I can. I assume that when I get back to it, it will be in 10 years, and I’ll be half drunk. That way, when I do get back to it, I can read it and understand it quickly.

I also believe that the code itself needs to be readable, not just well commented. Comments are great and I will swear by them all day long, however, I need the code to be readable or comments will be completely lost on me.

Some examples:


# this is not very readable (what is an "isdir" anyway): 
if os.path.isdir("C:\file_path"): 

# this feels better, i think: 
if pyfile.is_dir("C:\file_path"): 

Not convinced? Ok, next example: getting the influence list from a skinned mesh in Maya.

Putting aside the fact that you have to feed it a skinCluster instead of a mesh, the default Maya command is still confusing. Since the commands can be used in query mode or command mode, I end up having to scan the code for “query=”. I dont like it.

# Maya default: 
influences = cmds.skinCluster(cluster, query=True, influence=True) 

# how do you feel about this one? 
influences = myskin.influences(mesh) 

Still not convinced? Lets try to make a Maya reference.

# honestly, I can't read this. 
cmds.file("C:\file_path", reference=True, ignoreVersion=True, namespace=prefix) 

# That's much better. 
reference.create("C:\file_path", namespace) 

If this last example does not convince you, nothing will.

# get the name of a file: 
name = os.path.basename(os.path.splitext(file_path)[0])  #WTF?! 

# or: 
name = pyfile.name(file_path)

Trust me on this, your future self will be very thankful that you spent the time making sure he could read your chicken scratches.

So, what do you think? Comment away, and we can have a fun discussion.

// Isoparm

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.