Coding Style (Python)

The Python code in this project follows the following standard.

Naming Conventions

• All variables (arguments), functions (methods) and files should be in snake_case. Classes should be in PascalCase.
• Names may contain ONE underscore (_) at the beginning or the end of the name, in order to differentiate from the keywords or other variables in the parent scope.
• Good:

class MyClass:
    my_variable = 0
 
    def my_function(
        my_argument_a,
        my_argument_b_,
        _my_argument_c
    ):
        pass

• Bad:

class myClass:  # Not PascalCase.
    myVariable = 0  # Not snake_case.
 
    def myFunction(
        myArgumentA,  # Not snake_case.
        myArgumentB,  # Not snake_case.
        __myArgumentC  # Not snake_case, and two underscores.
    ):
        pass

Indentation

• Use 4 spaces for indentation. Do NOT use tabs.
• Good:

def my_function():
    if True:
        # Do something.

• Bad:

def my_function():
    if True:
    # Do something.

Line Length

• The maximum line length should be 120 characters. You may need to break long lines into multiple lines.
• Good:

my_variable = (
    "This is a very very very very very very very very very very very very very very very very long string"
    "that needs to be broken into multiple lines."
)

• Bad:

my_variable = "This is a very very very very very very very very very very very very very very very very long string that needs to be broken into multiple lines."

Spaces

• Always put a space after a comma.
• Always put a space before and after an operator.
• Do NOT put a space after the opening and before the closing parentheses.
• Do NOT put a space after the opening and before the closing square brackets.
• Do NOT put a space after the opening and before the closing curly braces.
• Good:

my_variable = 0
b = 1 + (4 * 5)

• Bad:

my_variable=0
b = 1+( 4*5 )

Comments

• Use # for single-line comments. Use """</tt> for docstrings. - Put a space after the <tt>\#</tt> character. If it is an inline comment, put two spaces before the <tt>\#</tt> character. - <strong>Good</strong>: @icode{python} # This is a single-line comment. def my_function(): """ This is a docstring. """ do_something() # This is an inline comment. @endicode - <strong>Bad</strong>: @icode{python} #This is a single-line comment. def my_function(): # This is not a docstring. do_something()# This is an inline comment. @endicode @section autotoc_md32 Imports - Import statements should be on separate lines, and should be in alphabetical order. \remark Use the <tt>isort</tt> package to sort the imports. \attention Do <strong>NOT</strong> use <tt>from module import *</tt>. This will seriously affect the readability of the code. - <strong>Good</strong>: @icode{python} import os import sys @endicode - <strong>Bad</strong>: @icode{python} import os, sys @endicode @section autotoc_md33 File Structure - The file structure should be as follows: @icode{python} # Header comments... # Standard library imports import os import sys # Third-party imports import numpy as np # Local application imports from my_module import my_function # Constants MY_CONSTANT = 0 # Classes class MyClass: pass # Functions def my_function(): pass # Main code (driver code) if necessary / for testing if __name__ == "__main__": my_function() @endicode @section autotoc_md34 Python Version - The code should be compatible with the last 3 subversions of Python. The code should be tested with the latest version of Python. \note As of now, the latest version is Python 3.12. Therefore, the last 3 subversions are 3.10, 3.11, and 3.12. - Be very careful with version-specific features. If you use a feature that is not available in the last 3 subversions, just do not use it. <hr> \remark <br> @section autotoc_md35 Tools <br><br> The Python code in this project follows the <a href="https://black.readthedocs.io/en/stable/" >Black code style. The code should be formatted using Black before pushing to the repository.
  
  

Formatting

The code should be formatted using Black. You can install Black using pip:

pip install black

OR install everything in the pyproject.toml file:

pip install .

To format the code, use the following command:

black .

and it will format the code according to the Black code style.

Sorting Imports

The imports should be sorted using isort. You can install isort using pip:

pip install isort

To sort the imports, use the following command:

isort .

and it will sort the imports according to alphabetical order.