Clean Code Python: Code snippets for blog post "Writing Appreciable Python Code"

clean_code__accessing_resources_best.py

from pathlib import Path

text = Path(text_filepath).read_text()
image_data = Path(binary_filepath).read_bytes()

clean_code__accessing_resources_good.py

import os

text_filepath = os.path.join("user", "me", "somefile.txt")
with open(text_filepath) as fp:
    text = fp.read()
print(text)

binary_filepath = os.path.join("user", "me", "some_image.jpg")
with open(binary_filepath, 'b') as fp:
    image_data = # <read image data> from fp
print(image_data)

clean_code__accessing_resources_very_bad.py

import os

text_filepath = os.path.join("user", "me", "somefile.txt")
fp = open(text_filepath)
text = fp.read()
print(text)
fp.close()

binary_filepath = os.path.join("user", "me", "some_image.jpg")
fp = open(binary_filepath, 'b')
image_data = <read image data> from fp
print(image_data)
fp.close()

clean_code__documentation_bad.py

def calc_relative_refractive_index(v1, v2):
    ...
    return v1/v2

clean_code__documentation_best.py

def calc_relative_refractive_index(light_velocity_1: float, light_velocity_2: float) -> float:
    """ Calculate relative refractive index of light between 2 media.

       Relative Refractive Index of Medium 1 with respect to medium 2 is the ratio of velocity of light in medium 1 and medium 2.


   Arguments:
       light_velocity_1 : Velocity of light in medium 1
       light_velocity_2 : Velocity of light in medium 2

    Returns:
         Relative refractive index.
    """
    ...
    return light_velocity_1 / light_velocity_2

clean_code__documentation_better.py

def calc_relative_refractive_index(light_velocity_1:float, light_velocity_2: float):
   """ Calculate relative refractive index between 2 media.
   """
   ...
   return light_velocity_1/light_velocity_2

clean_code__documentation_still_better.py

def calc_relative_refractive_index(light_velocity_1: float, light_velocity_2: float) -> float:
    """ Calculate relative refractive index between 2 media.

    Arguments:
       light_velocity_1 : Velocity of light in medium 1
       light_velocity_2 : Velocity of light in medium 2

    Returns:
         Relative refractive index.
    """
    ...
    return light_velocity_1 / light_velocity_2

clean_code__filesystem_nay.py

import os

basedir = "/user/me"
dirpath = os.path.join(basedir, "Documents", "datasets", "develop")
source_filepath = os.path.join(dirpath, "image_array.txt")
with open(source_filepath, 'r') as fp:
   lines = fp.readlines()
...
destination_filepath = os.path.join(dirpath, "image.jpg")
with open(destination_filepath, 'wb') as fp:
   fp.write(b"897689hiuh9")

clean_code__filesystem_yay.py

from pathlib import Path

basedir = Path("/user/me")

dirpath = basedir / "Documents" / "datasets" / "develop"
#  or
dirpath = basedir.joinpath("Documents", "datasets", "develop")

source_filepath = dirpath / "image_array.txt"
lines = source_filepath.read_text().splitlines()
...
destination_filepath = dirpath / "image.jpg"
destination_filepath.write_bytes(b"897689hiuh9")

clean_code__iterable_concat_bad.py

final_list = list1 + list2 + list3
final_set = set1 + set2 + set3
final_dict = dict1 + dict2 + dict3

final_list = list1 + range(5) # -> Raises TypeError (does not work with generators).

clean_code__iterable_concat_best.py

final_list = [*list1, *list2, *list3]
final_tuple = (*tuple1, *tuple2, *tuple3)

final_set = set1 | set2 | set3  # Must be all sets
final_dict = dict1 | dict2 | dict3  # Must be all dicts

final_set = set1 | range(5) # -> Raises TypeError (does not work with generators).

clean_code__iterable_concat_good.py

final_list = [*list1, *list2, *list3]
final_tuple = (*tuple1, *tuple2, *tuple3)
final_set = {*set1, *set2, *set3}
final_dict = {**dict1, **dict2, **dict3}

final_list = [*list1, *range(5)]  # Works with generators.

clean_code__multiline_bad.py

from typing import List, \
   Optional, \
   Union

total = a + \
   b + \
   c

long_text = "first" \
   "second" \
   "third"

clean_code__multiline_good.py

from typing import (
   List,
   Optional,
   Union,
)

total = (
        a
        + b
        + c
)
long_text = ("first"
            "second"
            "third"
             )

clean_code__naming_things_bad.py

def corr(df, th, c):
   ...

def correlation(dataframe, thresh, cols_list):
    ...

clean_code__naming_things_best.py

from pandas import DataFrame
from typing import List, Optional

def drop_correlated_features(
        data: DataFrame,
        correlation_threshold: float,
        subset_fields: Optional[List[str]] = None,
) -> DataFrame:
    ...

clean_code__naming_things_better.py

def drop_corr_cols(data, threshold, fields):
   ...

def drop_correlated_cols(data, threshold, fields):
    ...

clean_code__naming_verb_table.tsv

clean_code__one_function_one_action_bad.py

def fill_na_in_fields(data: DataFrame, fields: List[str]):
    data[fields].fillna(0, inplace=True)
    print(data.head())
    return data

fill_na_in_fields(some_data, ["cost", "properties"])

clean_code__one_function_one_action_best.py

from typing import List

from pandas import DataFrame


def fill_na_in_fields(data: DataFrame, fields: List[str]) -> DataFrame:
   return data[fields].fillna(0)

filled_in_data = fill_na_in_fields(data=some_data, fields=["cost", "properties"])
print(filled_in_data.head())

clean_code__one_function_one_action_better.py

def fill_na_in_fields(data: DataFrame, fields: List[str]):
   data = data[fields].fillna(0)
   return data

fill_na_in_fields(data=some_data, fields=["cost", "properties"])

clean_code__partial_functions_better.py

from functools import partial

diff_extras_example_function =  partial(example_function, some_data, fields=["cost", "properties"])

diff_extras_example_function(extra_field=None)
diff_extras_example_function(extra_field="area")
diff_extras_example_function(extra_field="agent")
diff_extras_example_function(extra_field="owner")

clean_code__partial_functions_suboptimal.py

example_function(some_data, fields=["cost", "properties"], extra_field=None)
example_function(some_data, fields=["cost", "properties"], extra_field="area")
example_function(some_data, fields=["cost", "properties"], extra_field="agent")
example_function(some_data, fields=["cost", "properties"], extra_field="owner")

clean_code__string_concat_avoid.py

text_fragment_1 = "This is bad."
text_fragment_2 = "Using + is a computationally expensive."
text_fragment_3 = " It also forces one to add join spaces within the string fragments themselves."
text = text_fragment_1 + text_fragment_2 + text_fragment_3

clean_code__string_concat_endorse.py

text_fragment_1 = "This is good."
text_fragment_2 = "Easier to read and faster to compute."
text_fragment_3 = "Also, the fragments don't need the join spaces."
text = f"{text_fragment_1} {text_fragment_2} {text_fragment_3}"

clean_code__string_interpolation_avoid.py

a_string = "%s s-formatted %s string", arg1, arg2

text = "Avoid string interpolation using {}".format(format_method_text)

clean_code__string_interpolation_endorse.py

fstring_text = "f-string"
text = f"Use {fstring_text}."

clean_code__string_logging_bad.py

import logging

logging.info(f"{arg1} f-formatted {arg2} string")
logging.info("%s s-formatted %s string" % (arg1, arg2))  # note the `%` after the string and before the args
logging.info("{} s-formatted {} string", arg1, arg2)  # valid if logging is well configured (not recommended)

clean_code__string_logging_good.py

import logging

logging.info("%s s-formatted %s string", arg1, arg2)  # note the `,` and NOT `%` after the string and before the args

clean_code__trivial_functions_bad.py

def fill_na_in_fields(data, fields):
   return data[fields].fillna(0)

filled_in_data = fill_na_in_fields(data=some_data, fields=["cost", "properties"])
print(filled_in_data.head())

clean_code__trivial_functions_better.py

filled_in_data = some_data[fields].fillna(0)
print(filled_in_data.head())

clean_code__typing_annotations_01.py

from typing import Sequence, Tuple

from pandas import DataFrame


def calc_anova(data: DataFrame, fields: Sequence[str]) -> Tuple[float, float]:
    ...

clean_code__typing_annotations_02.py

from typing import Optional, Union


def make_random_number(seed: Optional[int] = None) -> Union[int, float]:
    """ Returns a random number of type int OR float"""
    ...

clean_code__typing_annotations_03.py

from typing import Sequence

from pandas import DataFrame


def calc_anova(data: DataFrame, fields: Sequence[str]) -> tuple[float, float]:
    ...


def make_random_number(seed: int | None = None) -> int | float:
    """ Returns a random number of type int OR float"""
    ...