13 01 Best Practices - HannaAA17/Data-Scientist-With-Python-datacamp GitHub Wiki

The goal of this course is to transform you into a Python expert, and so the first chapter starts off with best practices when writing functions. We'll cover docstrings and why they matter and how to know when you need to turn a chunk of code into a function. You will also learn the details of how Python passes arguments to functions, as well as some common gotchas that can cause debugging headaches when calling functions.

Docstrings

Crafting a docstring

• Google Style

def function(arg_1, arg_2=42):
  """Description of what the function does.
 
  Args:
    args_1 (str): Description of arg_1 can break onto the next line 
      if needed.
    args_2 (int, optional): Write optional when an argument has a default value.
  
  Returns:
    bool: Optional description of the return value
    Extra lines are not indented.

  Raises:
    ValueError: Include any error types that the function intentionally raised.

  Notes:
  """

def count_letter(content, letter):
  """Count the number of times `letter` appears in `content`.

  Args:
    content (str): The string to search.
    letter (str): The letter to search for.

  Returns:
    int

  # Add a section detailing what errors might be raised
  Raises:
    ValueError: If `letter` is not a one-character string.
  """
  if (not isinstance(letter, str)) or len(letter) != 1:
    raise ValueError('`letter` must be a single character string.')
  return len([char for char in content if char == letter])

• Numpydoc

Retrieving docstrings

• use the attribute: .__doc__
• a function from inspect module: inspect.getdoc()

DRY and "Do one thing"

• Don't repeat yourself
• Do one thing

Pass by assignment

• Immutable
  • int
  • float
  • bool
  • string
  • bytes
  • tuple
  • frozenset
  • None
• Mutable
  • list
  • dict
  • set
  • bytearray
  • objects
  • functions

Mutable default arguments are dangerous

def foo(var=[]):
  var.append(1)
  return var
foo() #[1]
foo() #[1,1]

When you need to set a mutable variable as a default argument, always use None and then set the value in the body of the function.

def foo(var=None):
  if var is None:
    var = []
  var.append(1)
  return var
foo() #[1]
foo() #[1]