Coding Conventions

Aim of having good coding practices

• Readability
• Consistency
• Able to search for issues

Python

Function Comments

def function(arg1: argtype, arg2: argtype2) -> type:
  """
  Explain the overall function using sphinx docstring

  :param arg1: The derivative portion of the PID controller
  :param arg2: The integral portion of the PID controller
  :type arg2: [float, float]
  :return Explain the return code
  """

  # Longer comment explaining a block of code and what it does
  # and such
  line_of_code()
  line_of_code()
  for line in lines:
    line_of_code() 
    line_of_code()

  # Following a space, longer comment explaining a block of code and what it does
  # and such
  line_of_code()
  line_of_code()
  line_of_code() # Any small detail to note
  line_of_code()
  
  # Very complicated code
  very_complicated_line_of_code()

  # Very complicated code
  very_complicated_line_of_code()

  # Very complicated code
  very_complicated_line_of_code()

  # Very complicated code
  very_complicated_line_of_code()

Class Structure

class ClassInfo(ClassInherited)
  """
  What this class is about and how it is used
  """
  CLASS_PROPERTIES_ARE_IN_CAPITAL = 1

  def __init__()
    """
    Init function always first in the class
    """
    self.class_parameters_are_all_in_init_function: int = 2 # For class parameters, use the full name of the parameter so its clear what the user is changing, for normal variables in functions, a short name is ok (aka) a = Apple()
    pass
  
  @property
  def property1()
     """
     After init class state the properties
     """
     pass
  
  def operator_overload()
     pass

  def regular_function()
     """
     Finally, define the regular functions, for function names, use the full name of everything (not pos, loc, so its as detailed as possible
     """
     def subfunction()
        # Subfunction is used when the only function that uses the subfunction is in the function, no other code needs the function
        # For subfunctions, you don't need the full name of everything as it is not used by any other code
        pass
     
     pass

  @class_method/static_method
  def class_methods()
     """
     After init class state the properties
     """
     pass

• Use sphinx docstring for function comments
• init() function comes first, followed by properties and then regular functions, operator
• Use PEP8 as much as possible (https://realpython.com/python-pep8/)
• Class Files same as file names
• Specific to detailed for variable names and file names