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.
– 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.
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.
Would another programmer understand what x and y represent?
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.
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
Or use a hanging indent where every line but the first line is indented:
var = my_function(
arguement_1, arguement 2,
When using a hanging indent, remember no argument goes on the first line.
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 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 #
#This is a block comment
#The function prints hello world
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 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
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
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.
Happy clean coding.