I talked about the importance of giving your code tender loving care when writing it here. As a follow up, this is a short guideline of a few rules to follow to make you stand out from other programmers.

This article explores PEP-8 (Python Enhancement Proposal) a guide that you can use to make your python code more presentable and easy to read.

What is PEP-8?

PEP-8 is a guide that gives rules on how to write presentable code for readability and consistency. It is specifically designed for python, but it can also be used for other languages, depending on what you and your team decides. It was written in 20o1 by Guido van Rossum, Nick Coghlan and Barry Warsaw.

“Readability Counts”

– The Zen of Python

 

Why use PEP-8?

Because “Code is read more often than it is written” -Guido van Rossum. Writing takes a few hours, but you and others will have to go back to your code every other time to read it.

More on why it is important to write readable code

 

PEP-8 Rules

Naming Conventions

In code, everything (variables, functions, methods, classes, modules) has to have a name and not just any random names. Use descriptive names. If you are not used to it, you may think naming is taxing, but once you decide to only use meaningful names, then you may notice that your coding pace is a tad faster. Why? Because you don’t have to think about strange names to give your items.

Don’t

x="Lulu"

y ="Ngei"

Would another programmer understand what x and y represent?

Do

first_name="Lulu"

last_name="Ngei

Much better, right? Another thing to remember is when naming variables, methods, functions and modules, if they have more than one word, separate them with an underscore “_”, and write them in lowercase. my_var, my_function, method, module.py

For classes, use uppercase for each word like so; Class, MyClass and do not separate the words with an underscore.

 

Indentation

I must confess, this is the one thing I never cared about for the longest time. I didn’t even know there were rules on how to indent lines of code. Indentation or leading whitespace is what groups statements together.

For python 3, stick to one type of spacing for consistency and to avoid errors. Either use tab (recommended) or space. Python 3 does not allow the use of both. This is the expected error:

TabError: inconsistent use of tabs and spaces in indentation

Indentation after line breaks

Either indent after the opening bracket:

num = 3

if (num > 0 and

    num == 0):

    print(num, 'is even')

Or indent the second condition:

num = 5

if (x> 3 and

      x< 10):

    print(x)

Or use a hanging indent where every line but the first line is indented:

var = my_function(

           arguement_1, arguement 2,

           arguement 3)

When using a hanging indent, remember no argument goes on the first line.

 

Comments

The best practice in commenting is comment on code as you write it. They come out clearer and more descriptive that way.

Limit characters to 72, use complete and descriptive sentences and keep updating the comments as with changes in the code. Once you have that in mind, you’re good to go.

Block Comments

Block comments explain a section of code. It usually looks like an entire paragraph. When using block comments, here are the rules to follow:

• Indent block comments to the same level as the code they are describing
• Start every line with a # followed by a single space
• Separate paragraph with a line beginning with #

def my_function():

    #This is a block comment

    #The function prints hello world
    print("Hello World!")

Inline Comments

Inline comments come immediately next to a code statement. They describe the line of code they are next to. Avoid using inline comments a lot because they clutter code.

• Use sparingly
• 2 spaces from the code statement
• Don’t use them to explain the obvious. This gets redundant and is a waste of time

x = 10 #This is an inline comment

 

Whitespace

Whitespace makes code easier to read because things aren’t all bunched up. Too little of it makes your code look squeezed while too much of it makes your code look scattered. However, the right amount makes your code look perfectly neat.

Where to AVOID whitespaces

At the end of a line.

x = 5 

Inside parenthesis

my_list = [ 1, 2, 3 ]

Before a comma or semicolon or colon

print(x , y)

Before opening parenthesis of an argument list for a function

my_function ():

 

P.S Keep a maximum of 72 characters in a single line.

For more PEP-8 guidelines, look into the PEP-8 documentation.

How to automatically follow PEP-8 rules

Keeping track of all these rules can get taxing, that is why there are linters (programs that analyze code and flag errors) available as extensions for any text editor; Visual Studio Code, Sublime, Atom and VIM.

• pycodestyle
• flake8

 

Conclusion

To learn more about PEP-8, the documentation is a good place to start as well as this Real Python tutorial that I read to get a brief overview when I was starting out.

Happy clean coding.

<Lulu>