Python Style Guide: How to Write Clear and Neat Code

Writing code is one thing; writing beautiful, easily understandable code that others can use just as easily as you is a completely different matter altogether. It’s not always easy or intuitive to create neat code in Python, which begs the age-old question, do we have to? And what does neat, clear code even look like?

We’re going to break down what makes a Python style guide necessary, as well as the most important elements of a style guide. Read on to learn how you can perfect the way you write your Python code.

Why do you need a style guide?

How often have you come across a piece of code that took you far longer to understand than to read?

Chances are, if you regularly work with code written by other people, you’ll have had at least a few run-ins with some messy, barely-comprehensible code that makes you wish you had time to rewrite all of it. That’s the direct result of unclearly written code. It leads to poor code reuse and maintainability, which means it can’t be used in other places or easily maintained.

With a style guide, you can make sure that your own code never puts anyone else—including yourself—in that position.

Style guides see to two absolutely vital things in your code: legibility and consistency. By setting out rules for exactly how things should be written, style guides help you guarantee your coding style will be consistent all across the board. They also ensure that the status quo is legible code.

Let’s consider an analogy: say you’re looking for a consulting proposal template. The first one you come across switches between American and British English spellings, the second one’s layout is confusing, so you don’t know what to enter where, and the third uses a font that’s so hard to read, it slows you down. Without a style guide, that’s what unclear code looks like.

Now let’s consider what happens when the template creators use a style guide. Suddenly, you’ve got scannable proposal templates that are both easy to read and simple to use, because the font and layout are clear, and the spelling style is consistent. That’s the effect a style guide should have on your code.

Want More Career-focused News? Subscribe to Build Your Career Newsletter Today!

Free to use image sourced from Pexels

That’s why we need style guides like Python Enhancement Proposal 8 (PEP 8). Next, we’ll take a look at some of the most important components of that guide.

Indents

When you look at a segment of code, before you even read it, the first thing that strikes the eye is the way in which the person who wrote it used indents. That’s why it’s one of the most important aspects of a Python style guide.

The expected standard in Python is to use four spaces. This creates a clean look for your code, and makes it easier to find what you’re looking for at a glance.

Here’s an example of the difference it can make:

#Correct use of indentation
If (your_first_condition and
    your_second_condition):
    perform_specified_action

#Incorrect use of indentation
If (your_first_condition and
your_second_condition):
perform_specified_action

#Another incorrect use of indentation
If (your_first_condition and
		your_second_condition):
	perform_specified_action

Both of the latter examples make your code less legible. In the case of the first one, your eyes don’t intuitively know where the function stops, while the second one looks sloppy and somewhat random. In contrast, the first example is clean, well-laid-out, and easy to take in at a glance.

Names

Sure, it might be impossible to get every name fully consistent across objects, functions, and more, but that doesn’t mean we shouldn’t try. The more consistent your naming conventions are, the neater your code looks and the easier it is to find what you need.

One aspect of this is patterns. For example, let’s say you’re naming variables that relate to free electronic signatures. Here’s how to, and how not to, go about that:

#Good example
FreeSigs, FreeElectronicSigs, ElectronicSigsFree

#Bad example
freeSignatures, FreeElecSigs, electronic_signatures_free

As you can see, following one pattern consistently leads to a cleaner look. In the same way, you’ll want to find a good balance between overly long names, and names that are too short to convey any meaning.

#Good example
free_signatures, elec_signatures_free

#Bad example
electronic_signatures_available_for_free_online, esigfree, esf

You’ll also want to avoid starting a name of any kind with a number, or including special characters, especially if those characters are likely to crop up elsewhere in your code. Instead, do the right thing and choose clear, concise, no-nonsense names that anyone can understand.

Spaces

Blank lines and whitespaces can go a long way towards improving a code.

For example, if you’re writing multiple functions, it can get confusing pretty quickly if you don’t implement spaces between each individual one. Even if they’re not strictly necessary to make the code work, they help immensely with boosting legibility.

Free to use image sourced from Pexels

However, with that said, there are rules surrounding whitespaces. They shouldn’t be used immediately after a bracket, or before commas, semicolons, or colons. They also shouldn’t separate characters and opening brackets, regardless of whether it visually spaces things out.

Assignment operators, comparisons, and booleans should always be surrounded by whitespaces. This helps them remain legible and clear to readers.

Comments

Your code shouldn’t be written like a private journal, because it’s not only for you to read. Instead, you should use comments to address future readers and provide necessary clarification.

When writing comments, ensure you’re as clear and concise as possible. This isn’t the place for flowery language or extra words—get your point across in as few words as you can, and move on.

Python style guide: parting thoughts

It’s clear that a style guide creates rules that lead to cleaner, more legible code. That’s a wonderful thing for people who regularly work with code—and for anyone who’s trying to learn from the way others do things.

At the same time, a style guide doesn’t have to dictate every aspect of a piece of code. It should establish the way that code should look and be written, but it shouldn’t act as a way to restrict or limit the contents of your code.

In other words, your Python style guide should make it easier, never harder, to write more code.

Following the rules the style guide sets out should always help you create code you can be proud of. When the code looks beautiful and is legible to just about anyone who tries to read it, it’s a sign you’ve written great code.

About the Writer

Yauhen Zaremba is the Director of Demand Generation at PandaDoc, all-in-one document management software for almost all document types including this PandaDoc flooring contract template. He’s been a marketer for 10+ years, and for the last five years, he’s been entirely focused on the electronic signature, proposal, and document management markets. Yauhen has experience speaking at niche conferences where he enjoys sharing his expertise with other curious marketers. And in his spare time, he is an avid fisherman and takes nearly 20 fishing trips every year.