Introduction

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." - Martin Fowler, British software engineer, author and international speaker on software development

Python Coding Style Guide

Indentation

{: .image-with-shadow width="800px"}

{: .image-with-shadow width="1000px"}

Copy
# Add an extra level of indentation (extra 4 spaces) to distinguish arguments from the rest of the code that follows
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)


# Aligned with opening delimiter
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Use hanging indents to add an indentation level like paragraphs of text where all the lines in a paragraph are
# indented except the first one
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# Using hanging indent again, but closing bracket aligned with the first non-blank character of the previous line
a_long_list = [
    [[1, 2, 3], [4, 5, 6], [7, 8, 9]], [[0.33, 0.66, 1], [0.66, 0.83, 1], [0.77, 0.88, 1]]
    ]

# Using hanging indent again, but closing bracket aligned with the start of the multiline contruct
a_long_list2 = [
    1,
    2,
    3,
    # ...
    79
]

Maximum Line Length

Copy
# Using delimiters ( ) to wrap a multi-line expression
if (a == True and
    b == False):

# Using a backslash (\) for line continuation
if a == True and \
    b == False:
    pass

Should a Line Break Before or After a Binary Operator?

Copy
# PEP 8 compliant - easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

Blank Lines

Whitespace in Expressions and Statements

• immediately inside parentheses, brackets or braces

  Copy
  # PEP 8 compliant:
  my_function(colour[1], {id: 2})
  
  # Not PEP 8 compliant:
  my_function( colour[ 1 ], { id: 2 } )

  {: .language-python}
• Immediately before a comma, semicolon, or colon (unless doing slicing where the colon acts like a binary operator in which case it should should have equal amounts of whitespace on either side)

  Copy
  # PEP 8 compliant:
  if x == 4: print(x, y); x, y = y, x
  
  # Not PEP 8 compliant:
  if x == 4 : print(x , y); x , y = y, x

  {: .language-python}
• Immediately before the open parenthesis that starts the argument list of a function call

  Copy
  # PEP 8 compliant:
  my_function(1)
  
  # Not PEP 8 compliant:
  my_function (1)

  {: .language-python}
• Immediately before the open parenthesis that starts an indexing or slicing

  Copy
  # PEP 8 compliant:
  my_dct['key'] = my_lst[id]
  first_char = my_str[:, 1]
  
  # Not PEP 8 compliant:
  my_dct ['key'] = my_lst [id]
  first_char = my_str [:, 1]

  {: .language-python}
• More than one space around an assignment (or other) operator to align it with another

  Copy
  # PEP 8 compliant:
  x = 1
  y = 2
  student_loan_interest = 3
  
  # Not PEP 8 compliant:
  x                     = 1
  y                     = 2
  student_loan_interest = 3

  {: .language-python}
• Avoid trailing whitespace anywhere - it is not necessary and can cause errors. For example, if you use backslash (\) for continuation lines and have a space after it, the continuation line will not be interpreted correctly.
• Surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), booleans (and, or, not).
• Don't use spaces around the = sign when used to indicate a keyword argument assignment or to indicate a default value for an unannotated function parameter

  Copy
  # PEP 8 compliant use of spaces around = for variable assignment
  axis = 'x'
  angle = 90
  size = 450
  name = 'my_graph'
  
  # PEP 8 compliant use of no spaces around = for keyword argument assignment in a function call
  my_function(
      1,
      2,
      axis=axis,
      angle=angle,
      size=size,
      name=name)

String Quotes

Naming Conventions

• b (single lowercase letter)
• B (single uppercase letter)
• lowercase
• lower_case_with_underscores
• UPPERCASE
• UPPER_CASE_WITH_UNDERSCORES
• CapitalisedWords (or PascalCase) (note: when using acronyms in CapitalisedWords, capitalise all the letters of the acronym, e.g HTTPServerError)
• camelCase (differs from CapitalisedWords/PascalCase by the initial lowercase character)
• Capitalised_Words_With_Underscores

• Avoid using the characters 'l' (lowercase letter L), 'O' (uppercase letter o), or 'I' (uppercase letter i) as single character variable names. In some fonts, these characters are indistinguishable from the numerals one and zero. When tempted to use 'l', use 'L' instead.
• Avoid using non-ASCII (e.g. UNICODE) characters for identifiers
• If your audience is international and English is the common language, try to use English words for identifiers and comments whenever possible but try to avoid abbreviations/local slang as they may not be understood by everyone. Also consider sticking with either ‘American’ or 'British' English spellings and try not to mix the two.

Comments

Copy
def fahr_to_cels(fahr):
    # Block comment example: convert temperature in Fahrenheit to Celsius
    cels = (fahr + 32) * (5 / 9)
    return cels

Copy
def fahr_to_cels(fahr):
    cels = (fahr + 32) * (5 / 9)  # Inline comment example: convert temperature in Fahrenheit to Celsius
    return cels

• Why certain design or implementation decisions were adopted, especially in cases where the decision may seem counter-intuitive
• The names of any algorithms or design patterns that have been implemented
• The expected format of input files or database schemas

Copy
git checkout develop
git checkout -b style-fixes

Copy
git status

Copy
On branch style-fixes
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified:   inflammation-analysis.py

no changes added to commit (use "git add" and/or "git commit -a")

Copy
git add inflammation-analysis.py
git commit -m "Code style fixes."

Documentation Strings aka Docstrings

Copy
def fibonacci(n):
    """Calculate the nth Fibonacci number.

    A recursive implementation of Fibonacci array elements.

    :param n: integer
    :raises ValueError: raised if n is less than zero
    :returns: Fibonacci number
    """
    if n < 0:
        raise ValueError('Fibonacci is not defined for N < 0')
    if n == 0:
        return 0
    if n == 1:
        return 1

    return fibonacci(n - 1) + fibonacci(n - 2)

Python PEP 257 - Recommendations for Docstrings

Copy
"""A module for generating numerical sequences of numbers that occur in nature.

Functions:
  fibonacci - returns the Fibonacci number for a given integer
  golden_ratio - returns the golden ratio number to a given Fibonacci iteration
  ...
"""
...

Copy
help(fibonacci)

Copy
import numpy as np
def daily_mean(data):
    """Calculate the daily mean of a 2D inflammation data array for each day.

    :param data: A 2D data array with inflammation data (each row contains measurements for a single patient across all days).
    :returns: An array of mean values of measurements for each day.
    """
    return np.mean(data, axis=0)

Copy
def daily_max(data):
    """Calculate the daily maximum of a 2D inflammation data array for each day.

    :param data: A 2D data array with inflammation data (each row contains measurements for a single patient across all days).
    :returns: An array of max values of measurements for each day.
    """
    return np.max(data, axis=0)

Copy
def daily_min(data):
    """Calculate the daily minimum of a 2D inflammation data array for each day.

    :param data: A 2D data array with inflammation data (each row contains measurements for a single patient across all days).
    :returns: An array of minimum values of measurements for each day.
    """
    return np.min(data, axis=0)

Copy
git status

Copy
On branch style-fixes
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified:   inflammation/models.py

no changes added to commit (use "git add" and/or "git commit -a")

Copy
git add inflammation/models.py
git commit -m "Docstring improvements."

• push style-fixes to GitHub
• merge style-fixes into develop (once we are happy with the changes)
• push updates to develop branch to GitHub (to keep it up to date with the latest developments)
• finally, merge develop branch into the stable main branch

Copy
git push -u origin style-fixes
git checkout develop
git merge style-fixes
git push origin develop
git checkout main
git merge develop
git push origin main