From b76edd9b5e2fd0b64b1adc6c6f2679d5a75d69ec Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Fri, 9 Jul 2021 15:12:52 +0300 Subject: Improve wording in The Code Style Guide --- .../events/pages/code-jams/code-style-guide.html | 43 ++++++++++++---------- 1 file changed, 24 insertions(+), 19 deletions(-) (limited to 'pydis_site') diff --git a/pydis_site/templates/events/pages/code-jams/code-style-guide.html b/pydis_site/templates/events/pages/code-jams/code-style-guide.html index fbcb7612..31156da2 100644 --- a/pydis_site/templates/events/pages/code-jams/code-style-guide.html +++ b/pydis_site/templates/events/pages/code-jams/code-style-guide.html @@ -13,7 +13,7 @@ For end-users, the most important parts of the software are functionality and UI/UX. But for developers, there is one more important aspect - code style. While ugly code can do everything that it has to do, developing it further may be a difficult task, - especially if a developer didn't write an original code. + especially if the developer didn't write the original code. Which one of the following do you prefer to read and work with? 

MyPath = '/file.txt'
@@ -57,14 +57,15 @@ result = [
 
     

         The second is definitely easier to read and understand.
-        These scripts are small and if you read even first, you can understand what this code does pretty fast,
+        These scripts are small and even with the first code snippet you can understand what the code does pretty quickly,
         but what if the project has thousands and thousands of files in a really complex folder structure?
-        Do you want then code what looks like the first example?
-        You can save hours sometimes if you write beautiful code that follows style rules.
+        Do you want to work with code that looks like the first example?
+        You can save hours sometimes if you write beautiful code that follows the style guidelines.
     

     

-        The most important document of Python code style is PEP 8.
-        This gives the majority of all Python code style rules. This article will cover the most important rules of PEP 8.
+        The most important code style document for Python is PEP 8.
+        This Python Enhancement Proposal lays out the majority of all Python code style guidelines.
+        This article will cover the most important aspects of PEP 8.
     

 
     
Linters

@@ -75,12 +76,12 @@ result = [
         Flake8 points out to you rules what you did break in your code so you can fix them.
     

 
-    
Rules

+    
Guidelines

     
Basics

     
For indentation, you should use 4 spaces. Using tabs is not suggested, but if you do, you can't mix spaces and tabs.

     

         PEP 8 defines a maximum line length of 79 characters, however,
-        we are not so strict - we let teams choose a maximum line length between 79 and 119 characters.
+        we are not so strict - teams are welcome to choose a maximum line length between 79 and 119 characters.
     

     
2 blank lines should be left before functions and classes. Single blank lines are used to split sections and make logical breaks.

 
@@ -109,7 +110,7 @@ ListOfMyClass = List[MyClass]

Operators

If you have a chain of mathematic operations that you split into multiple lines, - you should put the operator at the beginning of the line and not to the end of the line. + you should put the operator at the beginning of the line and not the end of the line. 

# No
 result = (
@@ -124,7 +125,7 @@ result = (
     + 2
     * 3
 )
-

If you compare against None, you should use is and is not, but not compare equality.

+

If you ever check if something is equivalent to None, you should use is and is not instead of the == operator.

# No
 if variable == None:
     print("Variable is None")
@@ -134,7 +135,7 @@ if variable is None:
     print("Variable is None")

You should prefer using <item one> is not <item two> over not <item one> is <item two>. - Using second makes it harder to understand the expression. + Using the latter makes it harder to understand what the expression is trying to do. 

# No
 if not variable is None:
@@ -153,13 +154,13 @@ import pathlib, os
 # Yes
 import os
 import pathlib
-

Wildcard imports should be avoided in most cases. They make unclear where what comes from.

+

Wildcard imports should be avoided in most cases. It clutters the namespace and makes it less clear where functions or classes are coming from.

# No
 from pathlib import *
 
 # Yes
 from pathlib import Path
-

You should use isort imports order specification, what means:

+

You should use isort imports order specification, which means: