{% extends "events/base_sidebar.html" %} {% block breadcrumb %}
  • Events
  • Code Jams
  • The Code Style Guide
  • {% endblock %} {% block title %}The Code Style Guide{% endblock %} {% block event_content %}

    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 the developer didn't write the 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 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 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 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

    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.

    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 - 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.

    Naming

    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 PascalCase style.

    from typing import List
    
    
    class MyClass:
        pass
    
    ListOfMyClass = List[MyClass]

    Constant names should use the SCREAMING_SNAKE_CASE style.

    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).

    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 the end of the line.

    # No
    result = (
        1 +
        2 *
        3
    )
    
    # Yes
    result = (
        1
        + 2
        * 3
    )

    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")
    
    # 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 the latter makes it harder to understand what the expression is trying to do.

    # 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

    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 pathlib

    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, which means:

    Comments

    Comments are really important because they help everyone understand what code does. In general, comments should explain why you are doing something if it's not obvious. You should aim to write code that makes it obvious what it is doing and you can use the comments to explain why and provide some context.

    Keep in mind that just as important as having comments, is making sure they stay up to date. Out-of-date and incorrect comments confuse readers of your code (including future you).

    Comments content should start with a capital letter and be a full sentence(s).

    There are three types of comments: block comments, inline comments, and docstrings.

    Too much for you?

    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 %}