How to Write Beautiful Python Code With PEP 8
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Writing Beautiful Pythonic Code With PEP 8
PEP 8, sometimes spelled PEP8 or PEP-8, is a document that provides guidelines and best practices on how to write Python code. It was written in 2001 by Guido van Rossum, Barry Warsaw, and Nick Coghlan. The primary focus of PEP 8 is to improve the readability and consistency of Python code.
PEP stands for Python Enhancement Proposal, and there are several of them. A PEP is a document that describes new features proposed for Python and documents aspects of Python, like design and style, for the community.
This tutorial outlines the key guidelines laid out in PEP 8. It’s aimed at beginner to intermediate programmers, and as such I have not covered some of the most advanced topics. You can learn about these by reading the full PEP 8 documentation.
By the end of this tutorial, you’ll be able to:
- Write Python code that conforms to PEP 8
- Understand the reasoning behind the guidelines laid out in PEP 8
- Set up your development environment so that you can start writing PEP 8 compliant Python code
Free Bonus: 5 Thoughts On Python Mastery, a free course for Python developers that shows you the roadmap and the mindset you’ll need to take your Python skills to the next level.
Why We Need PEP 8
PEP 8 exists to improve the readability of Python code. But why is readability so important? Why is writing readable code one of the guiding principles of the Python language?
As Guido van Rossum said, “Code is read much more often than it is written.” You may spend a few minutes, or a whole day, writing a piece of code to process user authentication. Once you’ve written it, you’re never going to write it again. But you’ll definitely have to read it again. That piece of code might remain part of a project you’re working on. Every time you go back to that file, you’ll have to remember what that code does and why you wrote it, so readability matters.
If you’re new to Python, it can be difficult to remember what a piece of code does a few days, or weeks, after you wrote it. If you follow PEP 8, you can be sure that you’ve named your variables well. You’ll know that you’ve added enough whitespace so it’s easier to follow logical steps in your code. You’ll also have commented your code well. All this will mean your code is more readable and easier to come back to. As a beginner, following the rules of PEP 8 can make learning Python a much more pleasant task.
Following PEP 8 is particularly important if you’re looking for a development job. Writing clear, readable code shows professionalism. It’ll tell an employer that you understand how to structure your code well.
If you have more experience writing Python code, then you may need to collaborate with others. Writing readable code here is crucial. Other people, who may have never met you or seen your coding style before, will have to read and understand your code. Having guidelines that you follow and recognize will make it easier for others to read your code.
Naming Conventions
When you write Python code, you have to name a lot of things: variables, functions, classes, packages, and so on. Choosing sensible names will save you time and energy later. You’ll be able to figure out, from the name, what a certain variable, function, or class represents. You’ll also avoid using inappropriate names that might result in errors that are difficult to debug.
Note: Never use l , O , or I single letter names as these can be mistaken for 1 and 0 , depending on typeface:
Naming Styles
The table below outlines some of the common naming styles in Python code and when you should use them:
| Type | Naming Convention | Examples |
|---|---|---|
| Function | Use a lowercase word or words. Separate words by underscores to improve readability. | function , my_function |
| Variable | Use a lowercase single letter, word, or words. Separate words with underscores to improve readability. | x , var , my_variable |
| Class | Start each word with a capital letter. Do not separate words with underscores. This style is called camel case or pascal case. | Model , MyClass |
| Method | Use a lowercase word or words. Separate words with underscores to improve readability. | class_method , method |
| Constant | Use an uppercase single letter, word, or words. Separate words with underscores to improve readability. | CONSTANT , MY_CONSTANT , MY_LONG_CONSTANT |
| Module | Use a short, lowercase word or words. Separate words with underscores to improve readability. | module.py , my_module.py |
| Package | Use a short, lowercase word or words. Do not separate words with underscores. | package , mypackage |
These are some of the common naming conventions and examples of how to use them. But in order to write readable code, you still have to be careful with your choice of letters and words. In addition to choosing the correct naming styles in your code, you also have to choose the names carefully. Below are a few pointers on how to do this as effectively as possible.
How to Choose Names
Choosing names for your variables, functions, classes, and so forth can be challenging. You should put a fair amount of thought into your naming choices when writing code as it will make your code more readable. The best way to name your objects in Python is to use descriptive names to make it clear what the object represents.
When naming variables, you may be tempted to choose simple, single-letter lowercase names, like x . But, unless you’re using x as the argument of a mathematical function, it’s not clear what x represents. Imagine you are storing a person’s name as a string, and you want to use string slicing to format their name differently. You could end up with something like this:
This will work, but you’ll have to keep track of what x , y , and z represent. It may also be confusing for collaborators. A much clearer choice of names would be something like this:
Similarly, to reduce the amount of typing you do, it can be tempting to use abbreviations when choosing names. In the example below, I have defined a function db() that takes a single argument x and doubles it:
At first glance, this could seem like a sensible choice. db() could easily be an abbreviation for double. But imagine coming back to this code in a few days. You may have forgotten what you were trying to achieve with this function, and that would make guessing how you abbreviated it difficult.
The following example is much clearer. If you come back to this code a couple of days after writing it, you’ll still be able to read and understand the purpose of this function:
The same philosophy applies to all other data types and objects in Python. Always try to use the most concise but descriptive names possible.
Code Layout
How you lay out your code has a huge role in how readable it is. In this section, you’ll learn how to add vertical whitespace to improve the readability of your code. You’ll also learn how to handle the 79 character line limit recommended in PEP 8.
Blank Lines
Vertical whitespace, or blank lines, can greatly improve the readability of your code. Code that’s bunched up together can be overwhelming and hard to read. Similarly, too many blank lines in your code makes it look very sparse, and the reader might need to scroll more than necessary. Below are three key guidelines on how to use vertical whitespace.
Surround top-level functions and classes with two blank lines. Top-level functions and classes should be fairly self-contained and handle separate functionality. It makes sense to put extra vertical space around them, so that it’s clear they are separate:
Surround method definitions inside classes with a single blank line. Inside a class, functions are all related to one another. It’s good practice to leave only a single line between them:
Use blank lines sparingly inside functions to show clear steps. Sometimes, a complicated function has to complete several steps before the return statement. To help the reader understand the logic inside the function, it can be helpful to leave a blank line between each step.
In the example below, there is a function to calculate the variance of a list. This is two-step problem, so I have indicated each step by leaving a blank line between them. There is also a blank line before the return statement. This helps the reader clearly see what’s returned:
If you use vertical whitespace carefully, it can greatly improved the readability of your code. It helps the reader visually understand how your code splits up into sections, and how those sections relate to one another.
Maximum Line Length and Line Breaking
PEP 8 suggests lines should be limited to 79 characters. This is because it allows you to have multiple files open next to one another, while also avoiding line wrapping.
Of course, keeping statements to 79 characters or less is not always possible. PEP 8 outlines ways to allow statements to run over several lines.
Python will assume line continuation if code is contained within parentheses, brackets, or braces:
If it is impossible to use implied continuation, then you can use backslashes to break lines instead:
However, if you can use implied continuation, then you should do so.
If line breaking needs to occur around binary operators, like + and * , it should occur before the operator. This rule stems from mathematics. Mathematicians agree that breaking before binary operators improves readability. Compare the following two examples.
Below is an example of breaking before a binary operator:
You can immediately see which variable is being added or subtracted, as the operator is right next to the variable being operated on.
Now, let’s see an example of breaking after a binary operator:
Here, it’s harder to see which variable is being added and which is subtracted.
Breaking before binary operators produces more readable code, so PEP 8 encourages it. Code that consistently breaks after a binary operator is still PEP 8 compliant. However, you’re encouraged to break before a binary operator.
Indentation
“There should be one—and preferably only one—obvious way to do it.”
— The Zen of Python
Indentation, or leading whitespace, is extremely important in Python. The indentation level of lines of code in Python determines how statements are grouped together.
Consider the following example:
The indented print statement lets Python know that it should only be executed if the if statement returns True . The same indentation applies to tell Python what code to execute when a function is called or what code belongs to a given class.
The key indentation rules laid out by PEP 8 are the following:
- Use 4 consecutive spaces to indicate indentation.
- Prefer spaces over tabs.
Tabs vs. Spaces
As mentioned above, you should use spaces instead of tabs when indenting code. You can adjust the settings in your text editor to output 4 spaces instead of a tab character, when you press the Tab key.
If you’re using Python 2 and have used a mixture of tabs and spaces to indent your code, you won’t see errors when trying to run it. To help you to check consistency, you can add a -t flag when running Python 2 code from the command line. The interpreter will issue warnings when you are inconsistent with your use of tabs and spaces:
If, instead, you use the -tt flag, the interpreter will issue errors instead of warnings, and your code will not run. The benefit of using this method is that the interpreter tells you where the inconsistencies are:
Python 3 does not allow mixing of tabs and spaces. Therefore, if you are using Python 3, then these errors are issued automatically:
You can write Python code with either tabs or spaces indicating indentation. But, if you’re using Python 3, you must be consistent with your choice. Otherwise, your code will not run. PEP 8 recommends that you always use 4 consecutive spaces to indicate indentation.
Indentation Following Line Breaks
When you’re using line continuations to keep lines to under 79 characters, it is useful to use indentation to improve readability. It allows the reader to distinguish between two lines of code and a single line of code that spans two lines. There are two styles of indentation you can use.
The first of these is to align the indented block with the opening delimiter:
Sometimes you can find that only 4 spaces are needed to align with the opening delimiter. This will often occur in if statements that span multiple lines as the if , space, and opening bracket make up 4 characters. In this case, it can be difficult to determine where the nested code block inside the if statement begins:
In this case, PEP 8 provides two alternatives to help improve readability:
Add a comment after the final condition. Due to syntax highlighting in most editors, this will separate the conditions from the nested code:
Add extra indentation on the line continuation:
An alternative style of indentation following a line break is a hanging indent. This is a typographical term meaning that every line but the first in a paragraph or statement is indented. You can use a hanging indent to visually represent a continuation of a line of code. Here’s an example:
Note: When you’re using a hanging indent, there must not be any arguments on the first line. The following example is not PEP 8 compliant:
When using a hanging indent, add extra indentation to distinguish the continued line from code contained inside the function. The following example is difficult to read because the code inside the function is at the same indentation level as the continued lines:
Instead, it’s better to use a double indent on the line continuation. This helps you to distinguish between function arguments and the function body, improving readability:
When you write PEP 8 compliant code, the 79 character line limit forces you to add line breaks in your code. To improve readability, you should indent a continued line to show that it is a continued line. There are two ways of doing this. The first is to align the indented block with the opening delimiter. The second is to use a hanging indent. You are free to chose which method of indentation you use following a line break.
Where to Put the Closing Brace
Line continuations allow you to break lines inside parentheses, brackets, or braces. It’s easy to forget about the closing brace, but it’s important to put it somewhere sensible. Otherwise, it can confuse the reader. PEP 8 provides two options for the position of the closing brace in implied line continuations:
Line up the closing brace with the first non-whitespace character of the previous line:
Line up the closing brace with the first character of the line that starts the construct:
You are free to chose which option you use. But, as always, consistency is key, so try to stick to one of the above methods.
Comments
“If the implementation is hard to explain, it’s a bad idea.”
— The Zen of Python
You should use comments to document code as it’s written. It is important to document your code so that you, and any collaborators, can understand it. When you or someone else reads a comment, they should be able to easily understand the code the comment applies to and how it fits in with the rest of your code.
Here are some key points to remember when adding comments to your code:
- Limit the line length of comments and docstrings to 72 characters.
- Use complete sentences, starting with a capital letter.
- Make sure to update comments if you change your code.
Block Comments
Use block comments to document a small section of code. They are useful when you have to write several lines of code to perform a single action, such as importing data from a file or updating a database entry. They are important as they help others understand the purpose and functionality of a given code block.
PEP 8 provides the following rules for writing block comments:
- Indent block comments to the same level as the code they describe.
- Start each line with a # followed by a single space.
- Separate paragraphs by a line containing a single # .
Here is a block comment explaining the function of a for loop. Note that the sentence wraps to a new line to preserve the 79 character line limit:
Sometimes, if the code is very technical, then it is necessary to use more than one paragraph in a block comment:
If you’re ever in doubt as to what comment type is suitable, then block comments are often the way to go. Use them as much as possible throughout your code, but make sure to update them if you make changes to your code!
Inline Comments
Inline comments explain a single statement in a piece of code. They are useful to remind you, or explain to others, why a certain line of code is necessary. Here’s what PEP 8 has to say about them:
- Use inline comments sparingly.
- Write inline comments on the same line as the statement they refer to.
- Separate inline comments by two or more spaces from the statement.
- Start inline comments with a # and a single space, like block comments.
- Don’t use them to explain the obvious.
Below is an example of an inline comment:
Sometimes, inline comments can seem necessary, but you can use better naming conventions instead. Here’s an example:
Here, the inline comment does give extra information. However using x as a variable name for a person’s name is bad practice. There’s no need for the inline comment if you rename your variable:
Finally, inline comments such as these are bad practice as they state the obvious and clutter code:
Inline comments are more specific than block comments, and it’s easy to add them when they’re not necessary, which leads to clutter. You could get away with only using block comments so, unless you are sure you need an inline comment, your code is more likely to be PEP 8 compliant if you stick to block comments.
Documentation Strings
Documentation strings, or docstrings, are strings enclosed in double ( «»» ) or single ( »’ ) quotation marks that appear on the first line of any function, class, method, or module. You can use them to explain and document a specific block of code. There is an entire PEP, PEP 257, that covers docstrings, but you’ll get a summary in this section.
The most important rules applying to docstrings are the following:
Surround docstrings with three double quotes on either side, as in «»»This is a docstring»»» .
Write them for all public modules, functions, classes, and methods.
Put the «»» that ends a multiline docstring on a line by itself:
For one-line docstrings, keep the «»» on the same line:
For a more detailed article on documenting Python code, see Documenting Python Code: A Complete Guide by James Mertz.
Whitespace in Expressions and Statements
Whitespace can be very helpful in expressions and statements when used properly. If there is not enough whitespace, then code can be difficult to read, as it’s all bunched together. If there’s too much whitespace, then it can be difficult to visually combine related terms in a statement.
Whitespace Around Binary Operators
Surround the following binary operators with a single space on either side:
Comparisons ( == , != , > , < . >= , <= ) and ( is , is not , in , not in )
Note: When = is used to assign a default value to a function argument, do not surround it with spaces.
When there’s more than one operator in a statement, adding a single space before and after each operator can look confusing. Instead, it is better to only add whitespace around the operators with the lowest priority, especially when performing mathematical manipulation. Here are a couple examples:
You can also apply this to if statements where there are multiple conditions:
In the above example, the and operator has lowest priority. It may therefore be clearer to express the if statement as below:
You are free to choose which is clearer, with the caveat that you must use the same amount of whitespace either side of the operator.
The following is not acceptable:
In slices, colons act as a binary operators. Therefore, the rules outlined in the previous section apply, and there should be the same amount of whitespace either side. The following examples of list slices are valid:
In summary, you should surround most operators with whitespace. However, there are some caveats to this rule, such as in function arguments or when you’re combining multiple operators in one statement.
When to Avoid Adding Whitespace
In some cases, adding whitespace can make code harder to read. Too much whitespace can make code overly sparse and difficult to follow. PEP 8 outlines very clear examples where whitespace is inappropriate.
The most important place to avoid adding whitespace is at the end of a line. This is known as trailing whitespace. It is invisible and can produce errors that are difficult to trace.
The following list outlines some cases where you should avoid adding whitespace:
Immediately inside parentheses, brackets, or braces:
Before a comma, semicolon, or colon:
Before the open parenthesis that starts the argument list of a function call:
Before the open bracket that starts an index or slice:
Between a trailing comma and a closing parenthesis:
To align assignment operators:
Make sure that there is no trailing whitespace anywhere in your code. There are other cases where PEP 8 discourages adding extra whitespace, such as immediately inside brackets, as well as before commas and colons. You should also never add extra whitespace in order to align operators.
Programming Recommendations
You will often find that there are several ways to perform a similar action in Python (and any other programming language for that matter). In this section, you’ll see some of the suggestions PEP 8 provides to remove that ambiguity and preserve consistency.
Don’t compare Boolean values to True or False using the equivalence operator. You’ll often need to check if a Boolean value is True or False. When doing so, it is intuitive to do this with a statement like the one below:
The use of the equivalence operator, == , is unnecessary here. bool can only take values True or False . It is enough to write the following:
This way of performing an if statement with a Boolean requires less code and is simpler, so PEP 8 encourages it.
Use the fact that empty sequences are falsy in if statements. If you want to check whether a list is empty, you might be tempted to check the length of the list. If the list is empty, it’s length is 0 which is equivalent to False when used in an if statement. Here’s an example:
However, in Python any empty list, string, or tuple is falsy. We can therefore come up with a simpler alternative to the above:
While both examples will print out List is empty! , the second option is simpler, so PEP 8 encourages it.
Use is not rather than not . is in if statements. If you are trying to check whether a variable has a defined value, there are two options. The first is to evaluate an if statement with x is not None , as in the example below:
A second option would be to evaluate x is None and then have an if statement based on not the outcome:
While both options will be evaluated correctly, the first is simpler, so PEP 8 encourages it.
Don’t use if x: when you mean if x is not None: . Sometimes, you may have a function with arguments that are None by default. A common mistake when checking if such an argument, arg , has been given a different value is to use the following:
This code checks that arg is truthy. Instead, you want to check that arg is not None , so it would be better to use the following:
The mistake being made here is assuming that not None and truthy are equivalent. You could have set arg = [] . As we saw above, empty lists are evaluated as falsy in Python. So, even though the argument arg has been assigned, the condition is not met, and so the code in the body of the if statement will not be executed.
Use .startswith() and .endswith() instead of slicing. If you were trying to check if a string word was prefixed, or suffixed, with the word cat , it might seem sensible to use list slicing. However, list slicing is prone to error, and you have to hardcode the number of characters in the prefix or suffix. It is also not clear to someone less familiar with Python list slicing what you are trying to achieve:
However, this is not as readable as using .startswith() :
Similarly, the same principle applies when you’re checking for suffixes. The example below outlines how you might check whether a string ends in jpg :
While the outcome is correct, the notation is a bit clunky and hard to read. Instead, you could use .endswith() as in the example below:
As with most of these programming recommendations, the goal is readability and simplicity. In Python, there are many different ways to perform the same action, so guidelines on which methods to chose are helpful.
When to Ignore PEP 8
The short answer to this question is never. If you follow PEP 8 to the letter, you can guarantee that you’ll have clean, professional, and readable code. This will benefit you as well as collaborators and potential employers.
However, some guidelines in PEP 8 are inconvenient in the following instances:
- If complying with PEP 8 would break compatibility with existing software
- If code surrounding what you’re working on is inconsistent with PEP 8
- If code needs to remain compatible with older versions of Python
Tips and Tricks to Help Ensure Your Code Follows PEP 8
There is a lot to remember to make sure your code is PEP 8 compliant. It can be a tall order to remember all these rules when you’re developing code. It’s particularly time consuming to update past projects to be PEP 8 compliant. Luckily, there are tools that can help speed up this process. There are two classes of tools that you can use to enforce PEP 8 compliance: linters and autoformatters.
Linters
Linters are programs that analyze code and flag errors. They provide suggestions on how to fix the error. Linters are particularly useful when installed as extensions to your text editor, as they flag errors and stylistic problems while you write. In this section, you’ll see an outline of how the linters work, with links to the text editor extensions at the end.
The best linters for Python code are the following:
pycodestyle is a tool to check your Python code against some of the style conventions in PEP 8.
Install pycodestyle using pip :
You can run pycodestyle from the terminal using the following command:
flake8 is a tool that combines a debugger, pyflakes , with pycodestyle .
Install flake8 using pip :
Run flake8 from the terminal using the following command:
An example of the output is also shown.
Note: The extra line of output indicates a syntax error.
These are also available as extensions for Atom, Sublime Text, Visual Studio Code, and VIM. You can also find guides on setting up Sublime Text and VIM for Python development, as well as an overview of some popular text editors at Real Python.
Autoformatters
Autoformatters are programs that refactor your code to conform with PEP 8 automatically. Once such program is black , which autoformats code following most of the rules in PEP 8. One big difference is that it limits line length to 88 characters, rather than 79. However, you can overwrite this by adding a command line flag, as you’ll see in an example below.
Install black using pip . It requires Python 3.6+ to run:
It can be run via the command line, as with the linters. Let’s say you start with the following code that isn’t PEP 8 compliant in a file called code.py :
You can then run the following command via the command line:
code.py will be automatically reformatted to look like this:
If you want to alter the line length limit, then you can use the —line-length flag:
Two other autoformatters, autopep8 and yapf , perform actions that are similar to what black does.
Another Real Python tutorial, Python Code Quality: Tools & Best Practices by Alexander van Tol, gives a thorough explanation of how to use these tools.
Conclusion
You now know how to write high-quality, readable Python code by using the guidelines laid out in PEP 8. While the guidelines can seem pedantic, following them can really improve your code, especially when it comes to sharing your code with potential employers or collaborators.
In this tutorial, you learned:
- What PEP 8 is and why it exists
- Why you should aim to write PEP 8 compliant code
- How to write code that is PEP 8 compliant
On top of all this, you also saw how to use linters and autoformatters to check your code against PEP 8 guidelines.
If you want to learn more about PEP 8, then you can read the full documentation, or visit pep8.org, which contains the same information but has been nicely formatted. In these documents, you will find the rest of the PEP 8 guidelines not covered in this tutorial.
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Writing Beautiful Pythonic Code With PEP 8
Get a short & sweet Python Trick delivered to your inbox every couple of days. No spam ever. Unsubscribe any time. Curated by the Real Python team.
About Jasmine Finer
Jasmine is a Django developer, based in London.
Each tutorial at Real Python is created by a team of developers so that it meets our high quality standards. The team members who worked on this tutorial are:
PEP8: руководство по написанию чистого и читаемого кода на Python
Когда дело доходит до написания крупных проектов или поддержки существующего кода, становится очень важным следовать определенным стандартам кодирования, чтобы обеспечить читаемость, понятность и поддерживаемость кода.
Один из таких стандартов — PEP8, который устанавливает рекомендации по стилю и форматированию кода на языке Python.
Введение
PEP8 — это документ, описывающий стандарты, которые разработчики должны следовать при написании кода на Python. Следование этим рекомендациям может значительно улучшить качество вашего кода, сделать его более читаемым и понятным для других разработчиков.
В этой статье мы рассмотрим основные правила, описанные в PEP8, и объясним, как их следовать, чтобы написать чистый, читаемый и поддерживаемый код на Python.
Причины использовать
PEP8 — это руководство по стилю кода для языка программирования Python. Он описывает рекомендации и правила для написания читаемого, понятного и консистентного кода на Python.
PEP8 важен для написания качественного кода на Python по нескольким причинам. Во-первых, он помогает сделать код более читаемым и понятным для других программистов, которые могут работать с вашим кодом. Это особенно важно, если вы работаете в команде или если ваш код будет использоваться другими людьми.
Во-вторых, соблюдение стандартов PEP8 может помочь сделать ваш код более консистентным. Это означает, что ваш код будет выглядеть более единообразно и просто, что упрощает его понимание и обслуживание.
В-третьих, соблюдение стандартов PEP8 может помочь обнаружить ошибки и потенциальные проблемы в вашем коде. Например, если вы используете нестандартное именование переменных или не соблюдаете правила отступов, это может привести к ошибкам или проблемам при чтении вашего кода.
Кроме того, многие инструменты разработки поддерживают стандарты PEP8 и могут помочь вам автоматически проверять соответствие вашего кода этим стандартам.
В целом, соблюдение стандартов PEP8 является важной практикой для написания качественного кода на Python. Он помогает сделать ваш код более читаемым, консистентным и устойчивым к ошибкам.
Основные правила
Основные правила PEP8 — это набор рекомендаций по оформлению кода на Python, который помогает сделать код более читаемым и понятным. Ниже я перечислю несколько основных правил PEP8:
Отступы
Используйте 4 пробела для каждого уровня отступа. Это правило помогает визуально выделить блоки кода и упрощает чтение кода. Использование символов табуляции или пробелов для отступов не рекомендуется, так как это может вызывать проблемы с отображением в разных текстовых редакторах.
Например:
Максимальная длина строки
Ограничьте длину строки не более чем 79 символами. Если строка длиннее, разбейте ее на несколько строк. Длинные строки могут быть трудны для чтения, особенно когда они выходят за границы окна редактора. Разбиение длинных строк на несколько строк с помощью продолжения строки с помощью символа обратной косой черты \ является хорошей практикой.
Например:
Пробелы
Используйте один пробел между операторами и операндами. Не используйте пробелы для выделения скобок вокруг аргументов функций. Это правило помогает упростить код и сделать его более читабельным.
Например:
Именование
Используйте понятные и описательные имена переменных, функций и методов. Для имени переменных используйте строчные буквы, а для имен функций и методов — заглавные буквы. Это правило помогает делать ваш код более читаемым и понятным для других программистов.
Например:
Комментарии
Добавляйте комментарии к вашему коду, чтобы объяснить сложные участки кода.
Комментарии должны быть короткими, лаконичными и описательными, они должны помогать другим программистам понимать ваш код. Не используйте комментарии для описания очевидных вещей, таких как присваивание переменной значения, и избегайте комментариев в конце строки.
Например:
Импорты
Импортируйте модули в алфавитном порядке, разделяйте группы импортов пустой строкой и избегайте использования символа * . Это правило помогает упростить импорты и улучшить читабельность кода.
Пробелы вокруг операторов
Используйте пустые строки для разделения логически связанных частей кода. Не используйте несколько операторов на одной строке.
Используйте пробелы вокруг операторов (=, +, -, *, /, //, %, и т. д.), но не используйте пробелы вокруг символа индексирования или среза.
Например:
Названия функций и методов
Используйте глаголы в названиях функций и методов, используйте нижнее подчеркивание для разделения слов. Это правило помогает делать код более понятным и легче читаемым.
Например:
Название переменных
Используйте понятные и описательные названия для переменных, избегайте использования одиночных символов в качестве названий переменных, используйте нижнее подчеркивание для разделения слов.
Например:
Расположение функций и классов
Располагайте функции и классы логически в вашем коде. Разделяйте функции и классы пустыми строками, чтобы улучшить читабельность кода. Функции должны быть определены перед их использованием.
Например:
Длина строки
Строки не должны быть длиннее 79 символов. Если строка слишком длинная, ее можно разбить на несколько строк, используя скобки, запятые или операторы конкатенации.
Например:
Тройные кавычки
Используйте тройные кавычки для документации вашего кода. Это помогает другим программистам понимать ваш код и использовать его в своих проектах.
Например:
Полезные инструменты
Действительно, существует множество инструментов, которые помогают разработчикам Python следовать стандартам PEP8. Эти инструменты включают линтеры и автоматические форматировщики.
Линтеры — это инструменты, которые анализируют код и проверяют его соответствие стандартам PEP8. Они предупреждают разработчиков о нарушениях стандартов PEP8 и других проблемах в их коде. Некоторые из наиболее популярных линтеров для Python включают:
- pylint — это линтер для Python, который проверяет соответствие кода стандартам PEP8. Он также обнаруживает другие проблемы в коде, такие как синтаксические ошибки, неиспользуемые переменные и дублирование кода.
- flake8 — это линтер, который проверяет соответствие кода стандартам PEP8, а также обнаруживает другие проблемы в коде, такие как неиспользуемые импорты и неправильное форматирование строк.
- PyCharm — это IDE для Python, которая включает встроенный линтер, который проверяет соответствие кода стандартам PEP8 и другие проблемы в коде. Он также предлагает рекомендации по исправлению нарушений стандартов PEP8.
Автоматические форматировщики — это инструменты, которые автоматически форматируют код в соответствии со стандартами PEP8. Они упрощают процесс форматирования кода и позволяют разработчикам сосредоточиться на его содержимом. Некоторые из наиболее популярных автоматических форматировщиков для Python включают:
- Black — это автоматический форматировщик кода на Python, который форматирует код в соответствии со стандартами PEP8. Он удаляет неоднозначность в коде и делает его более понятным.
- autopep8 — это инструмент, который автоматически форматирует код в соответствии со стандартами PEP8. Он также может исправлять другие проблемы в коде, такие как синтаксические ошибки.
- YAPF — это автоматический форматировщик кода на Python, который форматирует код в соответствии со стандартами PEP8 и другими рекомендациями по стилю кодирования.
Использование линтеров и автоматических форматировщиков может значительно упростить процесс следования стандартам PEP8 и улучшить качество кода. Например, линтеры могут предупреждать о нарушениях стандартов PEP8 до того, как код будет отправлен на ревью, что помогает избежать ошибок, связанных со стилем кода. Автоматические форматировщики позволяют быстро и легко отформатировать код в соответствии со стандартами PEP8.
Кроме того, многие инструменты интегрируются с популярными средами разработки, такими как PyCharm и VS Code, что упрощает их использование и интеграцию в рабочий процесс разработки.
Важно отметить, что линтеры и автоматические форматировщики не могут полностью заменить ручное форматирование и проверку кода на соответствие стандартам PEP8. Иногда они могут допустить ошибки или предложить неоптимальные решения. Поэтому важно использовать эти инструменты в сочетании с ручной проверкой кода и соблюдением наилучших практик при написании кода на Python.
Дополнительные источники
Существует множество ресурсов и инструментов для дополнительного изучения PEP8 и его реализации в проектах.
Некоторые из них перечислены ниже:
- Официальный документ PEP8: Документ PEP8 можно найти на официальном сайте Python. Он содержит все основные правила и рекомендации по написанию чистого и понятного кода на Python.
- Flake8: Flake8 — это инструмент статического анализа кода на Python, который проверяет соответствие кода стандартам PEP8. Он также проверяет синтаксические ошибки, использование необъявленных переменных и другие нарушения.
- PyCharm: PyCharm — это интегрированная среда разработки (IDE) для Python, которая имеет встроенный инструмент PEP8. Он предупреждает вас, если ваш код нарушает стандарты PEP8, и предлагает исправления.
- Black: Black — это автоматический форматтер кода на Python, который следует стандартам PEP8. Он автоматически форматирует ваш код, чтобы он соответствовал стандартам PEP8, и также может использоваться для автоматического форматирования кода в больших проектах.
- pylint: pylint — это еще один инструмент статического анализа кода на Python, который проверяет соответствие кода стандартам PEP8. Он также предупреждает вас об использовании устаревших или небезопасных конструкций в вашем коде.
- Real Python: Real Python — это онлайн-платформа для изучения Python, которая содержит множество статей, учебных пособий и видеоуроков. Они предлагают руководства по написанию чистого и понятного кода на Python в соответствии с PEP8.
- Python Code Quality Authority: Python Code Quality Authority — это организация, которая управляет несколькими инструментами для проверки качества кода на Python, включая Flake8 и pylint. Они также поддерживают ряд стандартов и рекомендаций для написания чистого и понятного кода на Python.
Заключение
Следование правилам PEP8 поможет вам написать более чистый, понятный и поддерживаемый код на Python. Однако, не стоит забывать, что эти правила не являются абсолютными и всегда могут быть нарушены в некоторых случаях. Важно следить за своим стилем и придерживаться общепринятых стандартов в сообществе Python.
PEP 8
Python, подобно живому организму, развивается и приобретает новые возможности благодаря многочисленному международному сообществу согласно определенным правилам и стандартам PEP . PEP — Python Enhancement Proposal, предложения по развитию Python. Эти стандарты позволяют создавать унифицированную проектную документацию для новых утвержденных возможностей языка Python. Самый известный PEP имеет восьмой порядковый номер. PEP8 содержит перечень принципов написания красивого и лаконичного программного кода на языке Python.
Под названием каждого подраздела главы будет находиться по одному из 19 принципов философии Python (Zen of Python) . Попытайтесь «прочувствовать» то, что имел в виду автор. Также, если хочется, вместо русской адаптации этих постулатов, увидеть оригинальный текст Тима Петерса , можно запустив вот такую программу.
Для чего придуман PEP8? ¶
(Читаемость имеет значение)
PEP8 существует, чтобы улучшить «читабельность» кода. Но почему этот параметр имеет настолько большую важность? Почему написание хорошо читаемого кода — один из фундаментальных принципов языка Python?
Как сказал создатель Python, Гвидо Ван Россум: «Код читается гораздо чаще, чем пишется». Вы можете провести несколько минут, или весь день, в процессе написания куска кода для, к примеру, аутентификации пользователя. Написав его, однажды, вы не будете писать его еще раз. Но вы точно вернетесь, чтобы прочитать его еще и еще раз. Эта часть кода может быть частью проекта, над которым вы работаете. Каждый раз, возвращаясь к этому файлу, придется вспомнить, что этот код делает и почему вы написали это именно так.
Если вы начинающий программист Python, вам может быть тяжело запомнить, что делает определенная часть кода по прошествии нескольких дней после ее написания. Однако, если вы будете следовать рекомендациям PEP8, можете быть уверены, ваш код будет в полном порядке. Вы будете знать, что добавили достаточно пробелов, в соответствии с разделением на логические блоки кода.
Соблюдение PEP8 особенно важно, если вы в поисках вакансии python-разработчика. Чистый и читаемый код показывает высокий профессионализм. Он говорит работодателю о вашем понимании правильного структурирования программного кода.
Если же вы более опытный Python-программист, тогда с помощи PEP8 можно с легкостью объединиться с другими программистами для работы над одной задачей. Хорошо читаемый код имеет в данном случае особую критичность. Люди, ранее не видевшие вас, но знакомые с вашим кодом, будут читать, понимая идею, которую вы хотели донести.
Негласная договоренность об именах ¶
(Явное лучше, чем неявное)
При написании Python кода, необходимо придумывать имена многим вещам: переменным, функциям, классам, пакетам и так далее. Выбор разумных имен сэкономит вам время и силы в последствии. По названию нужно суметь понять, что представляет собой определенная переменная, функция или класс. Вы также избежите использования некорректных имен, которые могут привести к критическим ошибкам, плохо поддающимся отладке.
Не использовать одиночные буквы l, O, или I в качестве каких-либо имен из-за риска спутать их с 1 и 0, в зависимости от шрифта.
Стили именования ¶
В таблице ниже описаны некоторые из распространенных стилей именования в коде Python и указаны случаи, когда их следует использовать:
| Тип | Соглашение об именовании | Примеры |
|---|---|---|
| Функции | Используйте слово или слова в нижнем регистре. Для удобства чтения разделяйте слова подчеркиванием. | function, my_function |
| Переменные | Используйте одну строчную букву, слово или слова. Для удобства чтения разделяйте слова подчеркиванием. | x, var, my_variable |
| Классы | Каждое слово начинайте с заглавной буквы. Не разделяйте слова подчеркиванием. Этот стиль называется «дело верблюда». | Model, MyClass |
| Методы | Используйте слово или слова в нижнем регистре. Для удобства чтения разделяйте слова подчеркиванием. | class_method, method |
| Константы | Используйте одну заглавную букву, слово или слова. Для удобства чтения разделяйте слова подчеркиванием. | CONSTANT, MY_CONSTANT, MY_LONG_CONSTANT |
| Модули | Используйте короткие слова или слова в нижнем регистре. Для удобства чтения разделяйте слова подчеркиванием. | module.py, my_module.py |
| Пакеты | Используйте короткие слова или слова в нижнем регистре. Не разделяйте слова подчеркиванием. | package, mypackage |
Помимо выбора правильных стилей именования в вашем коде, вы также должны тщательно выбирать сами имена. Ниже приведены несколько советов, как сделать это максимально эффективно.
Правильный выбор имени ¶
Выбор имен для переменных, функций, классов и т. д. может оказаться неожиданно сложной задачей. При написании кода вы должны хорошо продумать свой выбор имен, так как это сделает ваш код более читаемым. Лучший способ назвать ваши объекты в Python — использовать описательные имена, чтобы было понятно, что представляет собой объект.
При именовании переменных у вас может возникнуть соблазн выбрать простые, состоящие из одной буквы имена в нижнем регистре, например x . Но если вы не используете x в качестве аргумента математической функции, непонятно, что представляет собой этот самый x . Представьте, что вы храните имя человека в виде строки и хотите использовать срез строки, чтобы по-другому отформатировать его имя.
Вы можете получить что-то вроде этого:
Это будет работать, но вам нужно будет отслеживать, что представляют собой x , y и z . Это также может сбивать с толку соавторов. Более правильный выбор имен будет примерно таким:
Точно так же, чтобы уменьшить количество набираемых вами букв, может возникнуть соблазн использовать сокращения при выборе имен. В приведенном ниже примере была определена функция db , которая принимает единственный аргумент x и удваивает его:
На первый взгляд, это может показаться очевидным выбором — это ведь отличное сокращением для double ! Но представьте, что вернетесь к этому коду через несколько дней. Скорее всего, вы забудете, какой смысл вкладывали в эту функцию и вполне можете подумать, что это сокращение от database .
Следующий пример еще более понятен:
Та же самая философия относится и ко всем прочим типам данных и объектов в Python. Всегда пробуйте использовать наиболее емкие и лаконичные названия.
Расположение кода ¶
(Красивое лучше, чем уродливое)
То, как Вы расположите ваш код, имеет огромную роль в повышении его читаемость. В этом разделе вы узнаете, как добавить вертикальные пробелы для улучшения восприятия вашего кода. Вы также узнаете, как правильно пользоваться ограничением в 79 символов на строку, рекомендованным в PEP8.
Монолитный код может быть труден для восприятия. Точно так же, слишком много пустых строк в коде делает его очень разреженным, что заставит читателя пролистывать его чаще, чем необходимо. Ниже приведены три основных правила использования вертикальных пробелов.
Окружите функции и классы верхнего уровня двумя пустыми строками. Функции и классы верхнего уровня должны быть самодостаточны и обрабатывать отдельные функции. Имеет смысл разместить вокруг них дополнительное вертикальное пространство, чтобы было ясно, что они разделены:
Обособьте определения методов внутри классов одной пустой строкой. Внутри класса все функции связаны друг с другом. Рекомендуется оставлять между ними только одну строку:
Используйте пустые строки внутри функций, чтобы четко показать шаги. Иногда сложная функция должна выполнить несколько шагов перед оператором return . Чтобы помочь читателю понять логику внутри функции, может быть полезно оставлять пустую строку между каждым шагом.
В приведенном ниже примере есть функция для вычисления дисперсии списка. Это двухэтапная задача, поэтому логично будет отделить каждый шаг, оставив между ними пустую строку. Перед оператором возврата также есть пустая строка. Это помогает читателю ясно увидеть, что возвращается:
Если вы правильно используете вертикальные пробелы, это может значительно улучшить читаемость вашего кода и помочь читателю визуально понять, что этот код делает.
Максимальная длина строки и разрыв строки ¶
PEP8 предлагает ограничить длину строки 79 символами. Это рекомендуется делать, чтобы вы имели возможность открывать несколько файлов рядом друг с другом, а также избегать переноса строк.
Конечно, не всегда возможно обеспечить длины всех операторов до 79 символов. PEP8 также описывает способы, позволяющие операторам занимать несколько строк. Python предполагает наличие продолжения строки, если код заключен в круглые, квадратные или фигурные скобки:
Если продолжение строки использовать не представляется возможным, можно также использовать обратную косую черту для разрыва строки:
Важно: если разрыв строки должен произойти вокруг бинарных операторов, таких как сложение или, например, умножение, он должен находиться перед оператором.
Отступы ¶
(Должен быть один очевидный способ сделать это)
Отступы или же пробелы в начале строки — крайне важная часть в синтаксисе Python. Как группируются операторы друг с другом операторы, в Python определяют именно уровни строк.
Отступ перед оператором вывода дает сигнал Python об условном выполнении только в случае, когда оператор if возвращает True . Ровно такой же отступ покажет Python, какой именно код выполнять при вызове функции или какой код имеет отношение к данному классу. Ключевых правил расстановки отступов всего два и они ниже:
- Используйте четыре последовательных пробела для отступа;
- Отдавайте предпочтение пробелам, а не табуляции.
Пробелы против Табуляции ¶
Вы можете настроить ваш редактор кода на вставку четырех пробелов, когда вы нажимаете клавишу Tab. Также необходимо иметь в виду, что в Python 3 запрещено смешение пробелов и табуляции. Изначально выберите, как именно вы будете выставлять отступы и придерживайтесь этого выбора. Иначе, вместо выполнения кода, вы получите ошибку.
Комментарии ¶
(Если реализацию трудно объяснить, это была плохая идея)
Используйте комментарии для документирования кода в том виде, в каком он написан. Это важно для ваших коллег и вашего понимания своего кода в будущем. Вот три важных ключевых момента, которые необходимо учитывать, при добавлении комментариев к коду:
- Используйте длину комментариев при документации не более 72 символов;
- Не используйте сокращения, начинайте предложения с заглавной буквы;
- Не забывайте актуализировать комментарии, при изменении кода.
Пример простейшего комментария:
Пробелы в выражениях и утверждениях ¶
(Разреженное лучше, чем плотное)
Полезность пробелов в выражениях и операторах трудно переоценить. Если пробелов недостаточно, код может быть трудночитаемым, так как все сгруппированы вместе. Если пробелов слишком много, может быть сложно визуально объединить строки кода в, логически связанные, блоки.
Окружите следующие бинарные операторы одним пробелом с каждой стороны:
- Операторы присвоения (=, +=, -= и т. п.)
- Сравнения (==, ! =, >, <. ≥, ≤) и (is, is not, in, not in)
- Логические (and, or, not)
Когда = используется для присвоения значения для аргумента функции, не окружайте его пробелами.
Рекомендации программисту ¶
(Простое лучше сложного)
Необходимо заметить, что в Python можно придумать несколько способов для выполнения одного и того же действия. Далее будет рассказано, как избавляться от двусмысленности при сохранении последовательности.
Использование оператора эквивалентности здесь не имеет необходимости, my_bool может иметь только два значения, True или False. Поэтому достаточно написать так:
Этот способ выполнения оператора if с логическим оператором проще и требует меньше кода, поэтому PEP8 рекомендует именно его.
Когда лучше проигнорировать PEP8 ¶
Однозначно ответить на этот вопрос довольно сложно. Если вы безукоризненно исполняете все предписания PEP8, можно с уверенностью гарантировать «чистоту», высокий уровень читаемости кода и профессионализм программиста. Что принесет пользу всем взаимодействующим с вашим кодом, от коллег до конечного заказчика продукта. Но все же некоторые рекомендации PEP8 неприменимы в следующих случаях:
- Если соблюдение PEP8 нарушит совместимость с существующим программным обеспечением;
- Если код, сопутствующий тому, над чем вы работаете, несовместим с PEP8;
- Если код нужно оставить совместимым с неактуальными версиями Python.
Заключение ¶
Теперь вам должно стать понятны способы создания высококачественного, читаемого кода Python, с помощью рекомендаций PEP8. Хотя они могут показаться тюрьмой для мозга творца, их соблюдение действительно может «прокачать» ваш код, в частности, когда речь заходит о разделении работы над ним с соавторами.
Если же у вас имеется желание углубиться в изучение тонкостей PEP8, можно ознакомиться с полной англоязычной документацией или посетить информационный ресурс pep8.org , содержащий ту же информацию, в более структурированном виде. В этих документах вы найдете, не попавшие в эту «выжимку», рекомендации.
Как писать красивый код с PEP 8. Часть #1
PEP 8 (иногда PEP8 или PEP-8) — документ, который содержит набор рекомендаций и практик, про то, как писать на Python. Написан в 2001 Гуидо ван Россумом, Барри Уорсо и Ником Когхланом. Основной целью PEP 8 является улучшение читаемости и согласованности кода.
PEP расшифровывается как Предложения по развитию Python и их огромное количество. PEP это документ, описывающий новые особенности предлагаемые для Python и документирует особенности Python, например, дизайн и стиль для сообщества.
В этом руководстве излагаются основные рекомендации, изложенные в PEP 8. Руководство предназначено для начинающих и программистов среднего уровня, и поэтому не затронуты некоторые из наиболее сложных тем. Вы можете узнать об этих темах, прочитав полную документацию по PEP 8 (англ и рус).
К концу этой статьи, вы сможете:
* Написать код Python, соответствующий PEP 8
* Понять обоснование руководящих принципов, изложенных в PEP 8
* Настроить среду разработки так, чтобы вы могли начинать писать Python код, совместимый с PEP 8
Читаемость имеет значение. (c) Дзен Python
PEP 8 существует для улучшения читабельности кода Python. Но почему так важна читабельность? Почему написание читаемого кода является одним из главных принципов языка Python?
Как сказал Гвидо ван Россум: «Код читается гораздо чаще, чем пишется». Вы можете потратить несколько минут или целый день на написание фрагмента кода для обработки аутентификации пользователя. После того, как вы написали, вы никогда не будете писать этот код снова. Однако вам определенно придется прочитать его заново. Этот фрагмент кода может остаться частью проекта, над которым вы работаете. Каждый раз, когда вы возвращаетесь к этому файлу, вы должны помнить, что делает этот код и почему вы его написали, поэтому читаемость имеет значение.
Если вы новичок в Python, то Вам будет трудно вспомнить, что делает фрагмент кода, через несколько дней или недель после его написания. Если вы будете следовать PEP 8, Вы можете быть уверены, что правильно назвали свои переменные. Вы будете знать, что добавили достаточно пробелов, чтобы легче было следовать логическим шагам в вашем коде. Вы также хорошо прокомментируете свой код. Все это будет означать, что Ваш код более читабелен и к нему легче вернуться. Как новичок, следование правилам PEP 8 может сделать изучение Python более приятной задачей.
Следование PEP 8 особенно важно, если вы ищете работу разработчиком. Написание четкого, читаемого кода демонстрирует профессионализм. Он скажет работодателю, что вы понимаете, как правильно структурировать свой код.
Если у вас большой опыт написания кода на Python, возможно, вам придется сотрудничать с другими разработчиками. Написание читаемого кода здесь имеет решающее значение. Другим людям, которые, возможно, никогда раньше не встречали вас и не видели ваш стиль кодирования, придется читать и понимать ваш код. Наличие руководств, которые вы соблюдаете и узнаёте, облегчит другим чтение вашего кода.
Явное лучше, чем неявное (с) Дзен Python
Когда вы пишете код на Python, вам нужно называть множество вещей: переменные, функции, классы, пакеты и так далее. Выбор правильных имен сэкономит ваше время и энергию. По названию вы сможете понять, что представляет собой определенная переменная, функция или класс. Вы также избежите использования неподходящих имен, которые могут привести к ошибкам, которые трудно отладить.
Примечание. Никогда не используйте однобуквенные имена l (прим: строчное L), O или I (прим: прописное i), поскольку их можно принять за 1 и 0, в зависимости от гарнитуры:
O = 2 # Это может выглядеть так, будто вы пытаетесь переопределить ноль, как число два
Стили именования:
Функции — используйте строчное слово(-а). Разделяйте слова нижним подчеркиванием для улучшения читаемости. Например: function, my_function
Переменные — используйте строчную букву, слово или слова. Разделяйте слова нижним подчеркиванием, чтобы улучшить читаемость. Например: x, var, my_variable
Классы — начинайте каждое слово с заглавной буквы. Не разделяйте слова подчеркиванием. Этот стиль называется ВерблюжийРегистр (прим: чаще всего употребляется всё же английский вариант названия: кэмэл кейс). Например: Model, MyClass
Методы — используйте строчные слова или слова. Разделяйте слова нижним подчеркиванием, чтобы улучшить читаемость. Например: class_method, method
Константы — используйте заглавные буквы, слово или слова. Разделяйте слова подчеркиванием, чтобы улучшить читаемость. (прим: в Python нет отдельного типа для констант. А так как в Python существует благодаря тому, что есть много соглашений, которые должны соблюдаться разработчиками. Поэтому и используется данное обозначение для констант. ) Например: CONSTANT, MY_CONSTANT, MY_LONG_CONSTANT
Модули — используйте короткое строчное слово(-а). Разделяйте слова нижним подчеркиванием, чтобы улучшить читаемость. Например: module.py , my_ module.py
Пакеты — используйте короткое строчное слово(-а). Не разделяйте слова подчеркиванием. Например: package, mypackage
Выше представлены некоторые из распространенных соглашений об именах и примеры их использования. Однако для того, чтобы написать читаемый код, вы все равно должны быть осторожны с выбором букв и слов. В дополнение к выбору правильного стиля именования в вашем коде, вы также должны тщательно выбирать имена. Ниже приведены несколько советов о том, как сделать это максимально эффективно.
Как выбрать имена
Выбор имен для ваших переменных, функций, классов и т.д. может быть сложной задачей. При написании кода вы должны тщательно продумать свои варианты именования, так как это сделает ваш код более читабельным. Лучший способ назвать ваши объекты в Python — это использовать описательные имена, чтобы прояснить, что представляет собой объект.
При именовании переменных у вас может возникнуть желание выбрать простые однобуквенные строчные имена, например, x. Но, если вы не используете x в качестве аргумента математической функции, неясно, что представляет собой x. Представьте, что вы храните имя человека в виде строки и хотите использовать нарезку строк, чтобы по-разному форматировать его имя. Вы можете получить что-то вроде этого:
Это будет работать, но вы должны будете отслеживать, что представляют собой x, y и z. Это также может сбивать с толку соавторов. Более ясный выбор имен представляет из себя что-то вроде этого:
name = ‘John Smith’
first_name, last_name = name.split()
print(last_name, first_name, sep=’, ‘)
Точно так же, чтобы уменьшить количество набираемого текста, может возникнуть соблазн использовать сокращения при выборе имен. В приведенном ниже примере мы определили функцию db (), которая принимает один аргумент x и удваивает его:
На первый взгляд это может показаться разумным выбором. db () может легко быть сокращением для удвоения. Но представьте, что вы вернетесь к этому коду через несколько дней. Возможно, вы забудете, что хотели сделать с помощью этой функции, и это затруднило бы возможность понять, как вы сокращали ее.
Следующий пример понятнее. Если вы вернетесь к этому коду через пару дней после его написания, вы все равно сможете прочитать и понять назначение этой функции:
Та же философия применима ко всем другим типам данных и объектам в Python. Всегда старайтесь использовать максимально сжатые, но описательные имена.
Красиво лучше, чем некрасиво. (c) Дзен Python
То, как вы выкладываете свой код, играет огромную роль в его читабельности. В этом разделе вы узнаете, как добавить вертикальный пробел для улучшения читабельности вашего кода. Вы также узнаете, как обрабатывать ограничение в 79 символов, рекомендованное в PEP 8.
Пустые линии
Вертикальные пробелы или пустые строки могут значительно улучшить читаемость вашего кода. Код, собранный вместе, может быть ошеломляющим и трудным для чтения. Точно так же, слишком много пустых строк в вашем коде делает его очень разреженным, и читателю может понадобиться прокрутить больше, чем необходимо. Ниже приведены три основных правила использования вертикальных пробелов.
Окружите функции и классы верхнего уровня двумя пустыми строками. Функции и классы верхнего уровня должны быть достаточно автономными и обрабатывать отдельные функции. Имеет смысл разместить вокруг них дополнительное вертикальное пространство, чтобы было ясно, что они разделены:
Определения метода внутри классов с одной пустой строкой. Внутри класса все функции связаны друг с другом. Рекомендуется оставлять между ними только одну строчку:
Используйте пустые строки внутри функций, чтобы показать четкие шаги. Иногда сложная функция должна выполнить несколько шагов перед оператором return. Чтобы помочь читателю понять логику внутри функции, может быть полезно оставить пустую строку между каждым шагом.
В приведенном ниже примере есть функция для расчета дисперсии списка. Это двухэтапная проблема, поэтому я обозначил каждый шаг, оставив между ними пустую строку. Существует также пустая строка перед оператором возврата. Это помогает читателю ясно увидеть, что возвращается:
for number in number_list:
sum_list = sum_list + number
mean = sum_list / len(number_list)
for number in number_list:
sum_squares = sum_squares + number**2
mean_squares = sum_squares / len(number_list)
return mean_squares — mean**2
Максимальная длина линии и разрыв строки
PEP 8 предполагает, что строки должны быть ограничены 79 символами. Это позволяет открывать несколько файлов рядом друг с другом, а также избегать переноса строк.
Конечно, сохранение утверждений длиной до 79 символов не всегда возможно. В PEP 8 изложены способы, позволяющие операторам выполнять несколько строк.
Python примет продолжение строки, если код содержится в круглых, квадратных и фигурных скобках:
def function(arg_one, arg_two,
Если невозможно использовать подразумеваемое продолжение, то вместо него можно использовать обратную косую черту:
from mypkg import example1, \
Однако, если вы можете использовать подразумеваемое продолжение, то вам следует всё же использовать продолжение.
Если разрыв строки должен происходить вокруг бинарных операторов, таких как + и *, это должно происходить перед оператором. Это правило вытекает из математики. Математики сходятся во мнении, что разрыв перед двоичными операторами улучшает читаемость. Сравните следующие два примера.
Ниже приведен пример разрыва перед бинарным оператором:
Вы можете сразу увидеть, какая переменная добавляется или вычитается, так как оператор находится рядом с той переменной, с которой вы работаете.
Теперь давайте рассмотрим пример разрыва после бинарного оператора:
Здесь сложнее увидеть, какая переменная добавляется, а какая вычитается.
Прерывание перед бинарными операторами создает более читаемый код, поэтому PEP 8 поощряет это. Код, который постоянно ломается после бинарного оператора, по-прежнему соответствует PEP 8. Тем не менее, вам рекомендуется разрывать перед двоичным оператором.
В следующей части рассмотрим отступы и как правильно комментировать код.
Все права принадлежат авторам статьи (команде Real Python).
Мною лишь переведена и адаптирована статья.