+ 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. + Which one of the following do you prefer to read and work with? +
+MyPath = '/file.txt'
+from pathlib import *
+import os.path,sys
+def check(p):
+ """Uses os.path.exist """
+ return os.path.exists(p)
+
+def getF(
+ p):
+ """Not sure what this do, this just worked.
+ """
+ return Path(p
+ )
+result=[check(MyPath),getF(MyPath)]or
+import os.path
+from pathlib import Path
+
+FILE_PATH = '/file.txt'
+
+
+def check_file_exists(path: str) -> bool:
+ """Checks does file exists in path. Uses os.path.exists."""
+ return os.path.exists(path)
+
+
+def get_path_object(path: str) -> Path:
+ """
+ Returns Path object of the path provided in arguments.
+
+ This is here for backward compatibility, will be removed in the future.
+ """
+ return Path(path)
+
+result = [
+ check_file_exists(FILE_PATH),
+ get_path_object(FILE_PATH),
+]+ 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, + 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. +
++ 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. +
+ ++ But everyone makes mistakes and there are so many style rules that can be really difficult to remember and always follow. + Luckily, we have amazing tools that help us - linters. While there are many linters, + we'd like code jam participants to use flake8. + Flake8 points out to you rules what you did break in your code so you can fix them. +
+ +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. +
+2 blank lines should be left before functions and classes. Single blank lines are used to split sections and make logical breaks.
+ +Module, file, function, and variable names (except type variables) should be lowercase and use underscores.
+# File: my_module.py/mymodule.py
+
+def my_function():
+ my_variable = "value"Class and type variable names should use the camel case style.
+from typing import List
+
+
+class MyClass:
+ pass
+
+ListOfMyClass = List[MyClass]Constant names should be all uppercase, and words should be separated with underscores.
+MY_CONSTANT = 1+ You should avoid single-character names, as these might be confusing. + But if you still do, you should avoid characters that may look like zero or one in some fonts: + "O" (uppercase o), "l" (lowercase L), and "I" (uppercase i). +
+ ++ 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. +
+# No
+result = (
+ 1 +
+ 2 *
+ 3
+)
+
+# Yes
+result = (
+ 1
+ + 2
+ * 3
+)If you compare against None, you should use is and is not, but not compare equality.
# No
+if variable == None:
+ print("Variable is None")
+
+# Yes
+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.
+
# No
+if not variable is None:
+ print("Variable is not None")
+
+# Yes - it is much easier to read and understand this than previous
+if variable is not None:
+ print("Variable is not None")Imports should be at top of the file, the only things that should be before them are module comments and docstrings.
+You shouldn't import multiple modules in one line, but give each module import its own line instead.
+# No
+import pathlib, os
+
+# Yes
+import os
+import pathlibWildcard imports should be avoided in most cases. They make unclear where what comes from.
+# No
+from pathlib import *
+
+# Yes
+from pathlib import PathYou should use isort imports order specification, what means:
+__future__ imports, standard library imports,
+ third-party library imports, and finally project imports.
+ import <package>
+ and after them from <package> import <items>.
+ from <package> import <items> format,
+ <items> should be ordered alphabetically, starting with bare module imports.
+ + Comments are really important because they help everyone understand what code does. + But as important as having comments is keeping them up-to-date. + Out-to-date, wrong comments confuse readers. +
+Comments content should start with a capital letter and be a full sentence(s).
+There are three types of comments:
+# what should be followed by a single space,
+ except for text indention inside the comment. To separate paragraphs, use one line containing only #.
+ if variable is None or variable == 1:
+ # If variable is None, something went wrong previously.
+ #
+ # Here starts a new important paragraph.+ Inline comments: You should prefer block comments over inline comments and use inline comments only where it is really necessary. + Never use inline comments to explain obvious things like what a line does. +
+If you want to use an inline comment on a variable, think first, maybe you can use a better variable name instead.
+
+ After code and before the start of inline comments should be at least two spaces.
+ Just like block comments, inline comments also have to start with # followed by a single space.
+
# Do not use inline comments to explain things
+# that the reader can understand even without the inline comment.
+my_variable = "Value!" # Assign value to my_variable
+
+# Here better variable name can be used like shown in the second line.
+x = "Walmart" # Shop name
+shop_name = "Walmart"
+
+# Sometimes, if something is not obvious, then inline comments are useful.
+# Example is from PEP 8.
+x = x + 1 # Compensate for border+ Docstrings: Last, but not least important comment type is docstring, which is a short version of documentation string. + Docstring rules haven't been defined by PEP 8, but by PEP 257 instead. + Docstrings should start and end with three quotes ("""). +
+There are two types of docstrings: one-line docstrings and multiline docstrings.
++ One-line docstrings have to start and end in the same line, while multiline docstrings start and end in different lines. + Multiline docstring has two parts: summary line and a longer description, which are separated by one empty line. + The multiline docstring start and end quotes should be at different lines than the content. +
+# This is a one-line docstring.
+"""This is one line module docstring."""
+
+
+# This is a multiline docstring.
+def my_function():
+ """
+ This is the summary line.
+
+ This is the description.
+ """+ Do all these style rules make your head explode? We have something for you! We have a song! + We have The PEP 8 Song (featuring lemonsaurus)! + Great way to get started with writing beautiful code. +
+{% endblock %} + +{% block sidebar %} + {% include "events/sidebar/code-jams/useful-information.html" %} +{% endblock %} diff --git a/pydis_site/templates/events/pages/code-jams/the-code-style-guide.html b/pydis_site/templates/events/pages/code-jams/the-code-style-guide.html deleted file mode 100644 index 68423dde..00000000 --- a/pydis_site/templates/events/pages/code-jams/the-code-style-guide.html +++ /dev/null @@ -1,257 +0,0 @@ -{% extends "events/base_sidebar.html" %} - -{% block breadcrumb %} -- 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. - Which one of the following do you prefer to read and work with? -
-MyPath = '/file.txt'
-from pathlib import *
-import os.path,sys
-def check(p):
- """Uses os.path.exist """
- return os.path.exists(p)
-
-def getF(
- p):
- """Not sure what this do, this just worked.
- """
- return Path(p
- )
-result=[check(MyPath),getF(MyPath)]or
-import os.path
-from pathlib import Path
-
-FILE_PATH = '/file.txt'
-
-
-def check_file_exists(path: str) -> bool:
- """Checks does file exists in path. Uses os.path.exists."""
- return os.path.exists(path)
-
-
-def get_path_object(path: str) -> Path:
- """
- Returns Path object of the path provided in arguments.
-
- This is here for backward compatibility, will be removed in the future.
- """
- return Path(path)
-
-result = [
- check_file_exists(FILE_PATH),
- get_path_object(FILE_PATH),
-]- 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, - 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. -
-- 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. -
- -- But everyone makes mistakes and there are so many style rules that can be really difficult to remember and always follow. - Luckily, we have amazing tools that help us - linters. While there are many linters, - we'd like code jam participants to use flake8. - Flake8 points out to you rules what you did break in your code so you can fix them. -
- -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. -
-2 blank lines should be left before functions and classes. Single blank lines are used to split sections and make logical breaks.
- -Module, file, function, and variable names (except type variables) should be lowercase and use underscores.
-# File: my_module.py/mymodule.py
-
-def my_function():
- my_variable = "value"Class and type variable names should use the camel case style.
-from typing import List
-
-
-class MyClass:
- pass
-
-ListOfMyClass = List[MyClass]Constant names should be all uppercase, and words should be separated with underscores.
-MY_CONSTANT = 1- You should avoid single-character names, as these might be confusing. - But if you still do, you should avoid characters that may look like zero or one in some fonts: - "O" (uppercase o), "l" (lowercase L), and "I" (uppercase i). -
- -- 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. -
-# No
-result = (
- 1 +
- 2 *
- 3
-)
-
-# Yes
-result = (
- 1
- + 2
- * 3
-)If you compare against None, you should use is and is not, but not compare equality.
# No
-if variable == None:
- print("Variable is None")
-
-# Yes
-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.
-
# No
-if not variable is None:
- print("Variable is not None")
-
-# Yes - it is much easier to read and understand this than previous
-if variable is not None:
- print("Variable is not None")Imports should be at top of the file, the only things that should be before them are module comments and docstrings.
-You shouldn't import multiple modules in one line, but give each module import its own line instead.
-# No
-import pathlib, os
-
-# Yes
-import os
-import pathlibWildcard imports should be avoided in most cases. They make unclear where what comes from.
-# No
-from pathlib import *
-
-# Yes
-from pathlib import PathYou should use isort imports order specification, what means:
-__future__ imports, standard library imports,
- third-party library imports, and finally project imports.
- import <package>
- and after them from <package> import <items>.
- from <package> import <items> format,
- <items> should be ordered alphabetically, starting with bare module imports.
- - Comments are really important because they help everyone understand what code does. - But as important as having comments is keeping them up-to-date. - Out-to-date, wrong comments confuse readers. -
-Comments content should start with a capital letter and be a full sentence(s).
-There are three types of comments:
-# what should be followed by a single space,
- except for text indention inside the comment. To separate paragraphs, use one line containing only #.
- if variable is None or variable == 1:
- # If variable is None, something went wrong previously.
- #
- # Here starts a new important paragraph.- Inline comments: You should prefer block comments over inline comments and use inline comments only where it is really necessary. - Never use inline comments to explain obvious things like what a line does. -
-If you want to use an inline comment on a variable, think first, maybe you can use a better variable name instead.
-
- After code and before the start of inline comments should be at least two spaces.
- Just like block comments, inline comments also have to start with # followed by a single space.
-
# Do not use inline comments to explain things
-# that the reader can understand even without the inline comment.
-my_variable = "Value!" # Assign value to my_variable
-
-# Here better variable name can be used like shown in the second line.
-x = "Walmart" # Shop name
-shop_name = "Walmart"
-
-# Sometimes, if something is not obvious, then inline comments are useful.
-# Example is from PEP 8.
-x = x + 1 # Compensate for border- Docstrings: Last, but not least important comment type is docstring, which is a short version of documentation string. - Docstring rules haven't been defined by PEP 8, but by PEP 257 instead. - Docstrings should start and end with three quotes ("""). -
-There are two types of docstrings: one-line docstrings and multiline docstrings.
-- One-line docstrings have to start and end in the same line, while multiline docstrings start and end in different lines. - Multiline docstring has two parts: summary line and a longer description, which are separated by one empty line. - The multiline docstring start and end quotes should be at different lines than the content. -
-# This is a one-line docstring.
-"""This is one line module docstring."""
-
-
-# This is a multiline docstring.
-def my_function():
- """
- This is the summary line.
-
- This is the description.
- """- Do all these style rules make your head explode? We have something for you! We have a song! - We have The PEP 8 Song (featuring lemonsaurus)! - Great way to get started with writing beautiful code. -
-{% endblock %} - -{% block sidebar %} - {% include "events/sidebar/code-jams/useful-information.html" %} -{% endblock %} -- cgit v1.2.3