Create The Code Style Guide under Code Jam pages

1 files changed, 299 insertions, 0 deletions

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
new file mode 100644
index 00000000..33b36d99
--- /dev/null
+++ b/pydis_site/templates/events/pages/code-jams/the-code-style-guide.html
@@ -0,0 +1,299 @@
+{% extends "events/base_sidebar.html" %}
+
+{% block breadcrumb %}
+    <li><a href="{% url "events:index" %}">Events</a></li>
+    <li><a href="{% url "events:page" path="code-jams" %}">Code Jams</a></li>
+    <li class="is-active"><a href="#">The Code Style Guide</a></li>
+{% endblock %}
+
+{% block title %}The Code Style Guide{% endblock %}
+
+{% block event_content %}
+    <p>
+        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?
+    </p>
+    <pre>
+        <code class="language-python">
+            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)]
+        </code>
+    </pre>
+    <p>or</p>
+    <pre>
+        <code class="language-python">
+            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),
+            ]
+        </code>
+    </pre>
+
+    <p>
+        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.
+    </p>
+    <p>
+        The most important document of Python code style is <b><a href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a></b>.
+        This gives the majority of all Python code style rules. This article will cover the most important rules of PEP 8.
+    </p>
+
+    <h2>Linters</h2>
+    <p>
+        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 <b><a href="https://flake8.pycqa.org/en/latest/">flake8</a></b>.
+        Flake8 points out to you rules what you did break in your code so you can fix them.
+    </p>
+
+    <h2>Rules</h2>
+    <h3>Basics</h3>
+    <p>For indentation, you should use 4 spaces. Using tabs is not suggested, but if you do, you can't mix spaces and tabs.</p>
+    <p>
+        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.
+    </p>
+    <p>2 blank lines should be left before functions and classes. Single blank lines are used to split sections and make logical breaks.</p>
+
+    <h3>Naming</h3>
+    <p>Module, file, function, and variable names (except type variables) should be lowercase and use underscores.</p>
+    <pre>
+        <code class="language-python">
+            # File: my_module.py/mymodule.py
+
+            def my_function():
+                my_variable = "value"
+        </code>
+    </pre>
+    <p>Class and type variable names should use the camel case style.</p>
+    <pre>
+        <code class="language-python">
+            from typing import List
+
+
+            class MyClass:
+                pass
+
+            ListOfMyClass = List[MyClass]
+        </code>
+    </pre>
+    <p>Constant names should be all uppercase, and words should be separated with underscores.</p>
+    <pre>
+        <code class="language-python">
+            MY_CONSTANT = 1
+        </code>
+    </pre>
+    <p>
+        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).
+    </p>
+
+    <h3>Operators</h3>
+    <p>
+        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.
+    </p>
+    <pre>
+        <code class="language-python">
+            # No
+            result = (
+                1 +
+                2 *
+                3
+            )
+
+            # Yes
+            result = (
+                1
+                + 2
+                * 3
+            )
+        </code>
+    </pre>
+    <p>If you compare against <code>None</code>, you should use <code>is</code> and <code>is not</code>, but not compare equality.</p>
+    <pre>
+        <code class="language-python">
+            # No
+            if variable == None:
+                print("Variable is None")
+
+            # Yes
+            if variable is None:
+                print("Variable is None")
+        </code>
+    </pre>
+    <p>
+        You should prefer using <code><item one> is not <item two></code> over <code>not <item one> is <item two></code>.
+        Using second makes it harder to understand the expression.
+    </p>
+    <pre>
+        <code class="language-python">
+            # 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")
+        </code>
+    </pre>
+ 
+    <h3>Imports</h3>
+    <p>Imports should be at top of the file, the only things that should be before them are module comments and docstrings.</p>
+    <p>You shouldn't import multiple modules in one line, but give each module import its own line instead.</p>
+    <pre>
+        <code class="language-python">
+            # No
+            import pathlib, os
+
+            # Yes
+            import os
+            import pathlib
+        </code>
+    </pre>
+    <p>Wildcard imports should be avoided in most cases. They make unclear where what comes from.</p>
+    <pre>
+        <code class="language-python">
+            # No
+            from pathlib import *
+
+            # Yes
+            from pathlib import Path
+        </code>
+    </pre>
+    <p>You should use <b><a href="https://pycqa.github.io/isort/">isort</a><b> imports order specification, what means:</p>
+    <ul>
+        <li>
+            <b>Group by type:</b> order of import types should be <code>__future__</code> imports, standard library imports,
+            third-party library imports, and finally project imports.
+        </li>
+        <li>
+            <b>Group by import way:</b> inside each group, first should come imports in format <code>import &lt;package&gt;</code>
+            and after them <code>from &lt;package&gt; import &lt;items&gt;</code>.
+        </li>
+        <li>
+            <b>Order imports alphabetically:</b> inside each import way group, imports should be ordered by package names.
+        </li>
+        <li>
+            <b>Order individual import items by type and alphabetically:</b> in <code>from &lt;package&gt; import &lt;items&gt;</code> format,
+            <code>&lt;items&gt;</code> should be ordered alphabetically, starting with bare module imports.
+        </li>
+    </ul>
+
+    <h3>Comments</h3>
+    <p>
+        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.
+    </p>
+    <p>Comments content should start with a capital letter and be a full sentence(s).</p>
+    <p>There are three types of comments:</p>
+    <ul>
+        <li>
+            <b>Block comments:</b> Probably most common comment type. Should be indented to the same level as the code they describe.
+            Each line in the block comment has to start with <code>#</code> what should be followed by a single space,
+            except for text indention inside the comment. To separate paragraphs, use one line containing only <code>#</code>.
+            <pre>
+                <code class="language-python">
+                    if variable is None or variable == 1:
+                        # If variable is None, something went wrong previously.
+                        #
+                        # Here starts a new important paragraph.
+                </code>
+            </pre>
+        </li>
+        <li>
+            <b>Inline comments:</b> 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 what line do. 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 <code>#</code> what should be followed by a single space.
+            <pre>
+                <code class="language-python">
+                    # 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
+                </code>
+            </pre>
+        </li>
+        <li>
+            <b>Docstrings:</b> 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 <a href="https://www.python.org/dev/peps/pep-0257">PEP 257</a> 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 sentence starting and ending quotes should be at different lines than the content.
+            <pre>
+                <code class="language-python">
+                    # 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.
+                        """
+                </code>
+            </pre>
+        </li>
+    </ul>
+
+    <h2>Too much for you?</h2>
+    <p>
+        Is all this PEP 8 rules stuff making your head exploding? We have something for you! We have a song!
+        We have <a href="https://www.youtube.com/watch?v=hgI0p1zf31k">The PEP 8 Song (featuring lemonsaurus)</a>!
+        Great way to get started with writing beautiful code.
+    </p>
+{% endblock %}
+
+{% block sidebar %}
+    {% include "events/sidebar/code-jams/useful-information.html" %}
+{% endblock %}