I came across this PSSE python script recently and thought it would serve as a good example to show how simply restructuring the code will make it more readable.

Writing readable code is important, especially if you plan to share your script with someone in another department or organisation. The person you share with can understand and use your code quickly, they may even further improve your code by adding new features. Conversely a difficult to read script is a chore to work with. Potential bugs are difficult to spot and you may miss the meaning of the code.

Can you work out the purpose of the script? What about the major steps it takes? Are the generators added as in-service or out of service generators? Are there any exceptions to this rule? My apologies for the line width of this original file, it won’t fit into many of your browsers. You can download the original file using the “view raw” link at the bottom of the Gist.

The revised version is a quick attempt at applying some of the following principals to code restructuring:

PEP8 Coding style

We use Python Enhancement Proposal 8 (PEP8) compliant coding techniques for an instant readability boost. Most Python developers write code that adheres to PEP8’s guidelines. Following it yourself will ensure that your code will look more like Python code, and can be picked up by someone else familiar with PEP8.

Accurate Comments

Should be used to document difficult parts of the code. Be careful not to confuse complex code with bad code that should be rewritten. If a section of code requires an inordinate amount of comments to explain how it works, perhaps that section could be rewritten in a simpler manner.

Make sure comments are updated along with any code that is being rewritten. It saves everyone time when the comments match what the code is doing. It is better to have no comments than it is to have incorrect comments.

Magic Number Removal

Numbers that are written throughout the code without any meaning attached. They are confusing to colleagues because it is not immediately obvious to a new reader of the code why the magic number exists. The original code had a significant number of magic numbers, we removed some of them but many remain.

Smaller Functions

We tried to identify common tasks and move that code into its own function. Smaller functions are often easier to understand and test and can be documented as completing one specific task. Here are some warning signs that your function is too long and needs to be split up into smaller functions:

• Many levels of indentation; and
• Your function is longer than 200 lines of code.

The new script also boasts status logging to file and we have turned on PSSE exceptions. We will explain why turning on PSSE exceptions is a good idea in future post. Please spend some time comparing both of the files, we’d love to hear if you think we could improve on our readability and why.