13 - Clean code/14 - Clean code in Python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "# Принципи на качествения код в Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Съдържание:\n",
    "- SOLID\n",
    "- Clean Code\n",
    "- PEP8\n",
    "- Pylint\n",
    "- Пример"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Писането на код е само една част от това да си програмист. В живота на едно парче код, то по-често ще бъде прочитано, отколкото променяно. В нашият програмистки живот, по-често ще ни се налага да четем код, отколкото да пишем. Затова едно от ключовите ни умения като програмист е това да пишем качествен и четим код."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Съществуват някои широко-разпространени добри практики за писане на качествен код (а и архитектура). Ще разгледаме някои тях"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SOLID"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "SOLID е колекция от принципи, имащи за цел да направят нашия (обектно-ориентиран) код по-четим, по-лесен за поддържане и по-гъвква. SOLID е акроним на 5 принципа, които ще разгледаме по-долу - **S**ingle-reponsibility principle, **O**pen-closed principle, **L**iskov substitution principle, **I**nterface segregation principle и **D**ependency inversion principle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Single-reponsibility"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Както името му подсказва, single-reponsibility принципа казва, че \"един клас не трябва да има повече от една причина да се променя\". На по-прост език, това означава, че един клас трябва да има една отговорност/дейност.\n",
    "\n",
    "Тази идея може да бъде разширена и към всички други програмни единици, не само класовете. Трябва да се стараем да пишем функции или класове, които правят едно нещо."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Нека разгледаме следната задача (source: [Advent of Code 2022, day 18, pt1](https://adventofcode.com/2022/day/18)):\n",
    "\n",
    "Получаваме списък от координати на кубчета в тримерното пространство. На изхода на програмата трябва да върнем броя на \"видимите\" страни на кубчетата - например, ако имаме едно кубче с координати (1, 1, 1), и второ кубче с координати (2, 1, 1), то броя на видимите страни е 10 (две от страните няма да се виждат, защото са долепени една до друга).\n",
    "\n",
    "Как бихме написали кода за тази задача ?\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10\n"
     ]
    }
   ],
   "source": [
    "def solution():\n",
    "    line = input()\n",
    "    lines = []\n",
    "    while line != '':\n",
    "        lines.append(line)\n",
    "        line = input()\n",
    "\n",
    "    cubes = []\n",
    "    for line in lines:\n",
    "        x, y, z = line.split(',')\n",
    "        cubes.append((int(x), int(y), int(z)))\n",
    "\n",
    "    sides = 0\n",
    "\n",
    "    for source_cube in cubes:\n",
    "        hidden_sides = 0\n",
    "        for target_cube in cubes:\n",
    "            diff_x = abs(source_cube[0] - target_cube[0])\n",
    "            diff_y = abs(source_cube[1] - target_cube[1])\n",
    "            diff_z = abs(source_cube[2] - target_cube[2])\n",
    "\n",
    "            if (diff_x == 1 and diff_y == 0 and diff_z == 0) or (diff_x == 0 and diff_y == 1 and diff_z == 0) or (diff_x == 0 and diff_y == 0 and diff_z == 1):\n",
    "                hidden_sides += 1\n",
    "\n",
    "        sides += 6 - hidden_sides\n",
    "    \n",
    "    print(sides)\n",
    "\n",
    "solution()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Очевидно горната функция `solution` прави много неща - какво правим, ако имаме бъг в решението ? Трябва да прегледаме целия код, което тук е само 30 реда, но представете си, че говорим за 300 реда. Също така, ако направим промяна, не е много сигурно, че няма да счупим някое друго парче код. Затова нека започнем прилагането на принципа за единстветана отговорност."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Първото нещо, което ни хрумва да направим, е да отделим входа, сметките и изхода в отделни функции."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The answer is 10\n"
     ]
    }
   ],
   "source": [
    "def handle_input() -> list[tuple[int, int, int]]:\n",
    "    line = input()\n",
    "    lines = []\n",
    "    while line != '':\n",
    "        lines.append(line)\n",
    "        line = input()\n",
    "\n",
    "    cubes = []\n",
    "    for line in lines:\n",
    "        x, y, z = line.split(',')\n",
    "        cubes.append((int(x), int(y), int(z)))\n",
    "    \n",
    "    return cubes\n",
    "\n",
    "def solution(cubes: list[tuple[int, int, int]]):\n",
    "    sides = 0\n",
    "\n",
    "    for source_cube in cubes:\n",
    "        hidden_sides = 0\n",
    "        for target_cube in cubes:\n",
    "            diff_x = abs(source_cube[0] - target_cube[0])\n",
    "            diff_y = abs(source_cube[1] - target_cube[1])\n",
    "            diff_z = abs(source_cube[2] - target_cube[2])\n",
    "\n",
    "            if (diff_x == 1 and diff_y == 0 and diff_z == 0) or (diff_x == 0 and diff_y == 1 and diff_z == 0) or (diff_x == 0 and diff_y == 0 and diff_z == 1):\n",
    "                hidden_sides += 1\n",
    "\n",
    "        sides += 6 - hidden_sides\n",
    "    \n",
    "    return sides\n",
    "\n",
    "def handle_output(sides: int):\n",
    "    print(f'The answer is {sides}')\n",
    "\n",
    "cubes = handle_input()\n",
    "result = solution(cubes)\n",
    "handle_output(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Една идея по-добре. Но все още нашите функции `handle_input` и `solution` правят повече от едно неща.\n",
    "\n",
    "Нека разгледаме в детайли `handle_input` - макар и кратка, тя прави две основни неща - приема входа от клавиатурата, и го конвертира от низ до наредена тройка от цели числа. Какво би станало, ако искаме вместо от клавиатурата, нашия вход да се чете от файл ? Или пък от графичен интерфейс ? Тази промяна не би трябвало да има общо с това как превръщаме низ към наредена тройка. Затова ще разделим `handle_input` на две по-малки функции."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def read_input() -> list[str]:\n",
    "    line = input()\n",
    "    lines = []\n",
    "    while line != '':\n",
    "        lines.append(line)\n",
    "        line = input()\n",
    "\n",
    "    return lines\n",
    "\n",
    "def transform_input(lines: list[str]) -> list[tuple[int, int, int]]:\n",
    "\n",
    "    # [f(x) for x in X]\n",
    "    cubes = []\n",
    "    for line in lines:\n",
    "        x, y, z = line.split(',')\n",
    "        cubes.append((int(x), int(y), int(z)))\n",
    "    \n",
    "    return cubes\n",
    "\n",
    "def solution(cubes: list[tuple[int, int, int]]):\n",
    "    sides = 0\n",
    "\n",
    "    for source_cube in cubes:\n",
    "        hidden_sides = 0\n",
    "        for target_cube in cubes:\n",
    "            diff_x = abs(source_cube[0] - target_cube[0])\n",
    "            diff_y = abs(source_cube[1] - target_cube[1])\n",
    "            diff_z = abs(source_cube[2] - target_cube[2])\n",
    "\n",
    "            if (diff_x == 1 and diff_y == 0 and diff_z == 0) or (diff_x == 0 and diff_y == 1 and diff_z == 0) or (diff_x == 0 and diff_y == 0 and diff_z == 1):\n",
    "                hidden_sides += 1\n",
    "\n",
    "        sides += 6 - hidden_sides\n",
    "    \n",
    "    return sides\n",
    "\n",
    "def handle_output(sides: int):\n",
    "    print(f'The answer is {sides}')\n",
    "\n",
    "\n",
    "lines = read_input()\n",
    "cubes = transform_input(lines)\n",
    "result = solution(cubes)\n",
    "handle_output(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Така вече, ако се наложи промяна в начина по който **четем** входа, няма да се налага да променяме функцията, която държи и логиката за трансформирането на входа. Или ако пък се промени формата на входа, трябва да променим само `transform_input`, без да пипаме `read_input`.\n",
    "\n",
    "Друг плюс от това разделение е, че функцията `read_input` вече не е обвързана по никакъв начин с конкретната задача - спокойно тя може да бъде преизползвана за решаването на други задачи, които изискват четене от клавиатурата.\n",
    "\n",
    "Можем обаче да отидем една стъпка по-напред - нека отделим логиката за трансформиране на само един ред, отделно."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The answer is 10\n"
     ]
    }
   ],
   "source": [
    "def read_input() -> list[str]:\n",
    "    line = input()\n",
    "    lines = []\n",
    "    while line != '':\n",
    "        lines.append(line)\n",
    "        line = input()\n",
    "\n",
    "    return lines\n",
    "\n",
    "def line_to_tuple(line: str) -> tuple[int, int, int]:\n",
    "    x, y, z = line.split(',')\n",
    "    return int(x), int(y), int(z)\n",
    "\n",
    "def transform_input(lines: list[str]) -> list[tuple[int, int, int]]:\n",
    "    return [line_to_tuple(line) for line in lines]\n",
    "\n",
    "def solution(cubes: list[tuple[int, int, int]]):\n",
    "    sides = 0\n",
    "\n",
    "    for source_cube in cubes:\n",
    "        hidden_sides = 0\n",
    "        for target_cube in cubes:\n",
    "            diff_x = abs(source_cube[0] - target_cube[0])\n",
    "            diff_y = abs(source_cube[1] - target_cube[1])\n",
    "            diff_z = abs(source_cube[2] - target_cube[2])\n",
    "\n",
    "            if (diff_x == 1 and diff_y == 0 and diff_z == 0) or (diff_x == 0 and diff_y == 1 and diff_z == 0) or (diff_x == 0 and diff_y == 0 and diff_z == 1):\n",
    "                hidden_sides += 1\n",
    "\n",
    "        sides += 6 - hidden_sides\n",
    "    \n",
    "    return sides\n",
    "\n",
    "def handle_output(sides: int):\n",
    "    print(f'The answer is {sides}')\n",
    "\n",
    "\n",
    "lines = read_input()\n",
    "cubes = transform_input(lines)\n",
    "result = solution(cubes)\n",
    "handle_output(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тук задаваме въпросите - имаме ли нужда да раздробяваме кода чак толкова и имаме ли нужда от функция, която е само един ред ?\n",
    "\n",
    "Отговора на двата въпроса е един и същ - зависи. Всичко опира до конкретната задача, и конкретния стил на човека - някои казват, че ако функцията е един ред, няма нужда от нея. Но пък за сметка на това, `transform_input` е по-лесно четимо от `[line_to_tuple(line) for line in lines]`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Нека сега приложим същите идеи и върху `solution`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Point(x=2, y=3, z=4)\n"
     ]
    },
    {
     "ename": "TypeError",
     "evalue": "'type' object is not subscriptable",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[1], line 8\u001b[0m\n\u001b[1;32m      5\u001b[0m p1 \u001b[39m=\u001b[39m Point(\u001b[39m2\u001b[39m, \u001b[39m3\u001b[39m, \u001b[39m4\u001b[39m)\n\u001b[1;32m      6\u001b[0m \u001b[39mprint\u001b[39m(p1)\n\u001b[0;32m----> 8\u001b[0m \u001b[39mdef\u001b[39;00m \u001b[39mread_input\u001b[39m() \u001b[39m-\u001b[39m\u001b[39m>\u001b[39m \u001b[39mlist\u001b[39;49m[\u001b[39mstr\u001b[39;49m]:\n\u001b[1;32m      9\u001b[0m     line \u001b[39m=\u001b[39m \u001b[39minput\u001b[39m()\n\u001b[1;32m     10\u001b[0m     lines \u001b[39m=\u001b[39m []\n",
      "\u001b[0;31mTypeError\u001b[0m: 'type' object is not subscriptable"
     ]
    }
   ],
   "source": [
    "def read_input() -> list[str]:\n",
    "    line = input()\n",
    "    lines = []\n",
    "    while line != '':\n",
    "        lines.append(line)\n",
    "        line = input()\n",
    "\n",
    "    return lines\n",
    "\n",
    "def line_to_tuple(line: str) -> tuple[int, int, int]:\n",
    "    x, y, z = line.split(',')\n",
    "    return int(x), int(y), int(z)\n",
    "\n",
    "def transform_input(lines: list[str]) -> list[tuple[int, int, int]]:\n",
    "    return [line_to_tuple(line) for line in lines]\n",
    "\n",
    "def is_side_hidden(first_cube: tuple[int, int, int], second_cube: tuple[int, int, int]) -> bool:\n",
    "    # diffs = [abs(first_cube[direction] - second_cube[direction]) for direction in range(3)]\n",
    "\n",
    "    # return sum(diffs) == 1\n",
    "\n",
    "    diff_x = abs(first_cube[0] - second_cube[0])\n",
    "    diff_y = abs(first_cube[1] - second_cube[1])\n",
    "    diff_z = abs(first_cube[2] - second_cube[2])\n",
    "\n",
    "    is_side_x_hidden = (diff_x == 1 and diff_y == 0 and diff_z == 0)\n",
    "    is_side_y_hidden = (diff_x == 0 and diff_y == 1 and diff_z == 0)\n",
    "    is_side_z_hidden = (diff_x == 0 and diff_y == 0 and diff_z == 1)\n",
    "\n",
    "    return is_side_x_hidden or is_side_y_hidden or is_side_z_hidden\n",
    "\n",
    "def count_visible_sides(cube: tuple[int, int, int], others: list[tuple[int, int, int]]) -> int:\n",
    "    return 6 - sum(1 for other in others if is_side_hidden(cube, other))\n",
    "\n",
    "def solution(cubes: list[tuple[int, int, int]]):\n",
    "    visible_sides = [count_visible_sides(cube, cubes) for cube in cubes]\n",
    "    return sum(visible_sides)\n",
    "\n",
    "def handle_output(sides: int):\n",
    "    print(f'The answer is {sides}')\n",
    "\n",
    "\n",
    "lines = read_input()\n",
    "cubes = transform_input(lines)\n",
    "result = solution(cubes)\n",
    "handle_output(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Спрямо първоначалното ни решение (което бе 29 реда), това вече е 42 реда - но е доста по-четимо, доста по-лесно за промяна и доста по-тестваемо. `is_side_hidden` може да бъде написана по-кратко, но по-четимия код е по-добър от по-краткия."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Open-closed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Open-closed принципа гласи, че софтуерните компоненти трябва да са отворени за разширение, но затворени за модификация."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Нека разгледаме примера, където имаме клас `Rectangle`, и функция която пресмята сумата от лицата на всички правоъгълници в списък."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "14\n"
     ]
    }
   ],
   "source": [
    "from typing import List\n",
    "\n",
    "class Rectangle:\n",
    "    def __init__(self, width, height):\n",
    "        self.width = width\n",
    "        self.height = height\n",
    "\n",
    "def sum_areas(rectangles: List[Rectangle]):\n",
    "    return sum(rect.width * rect.height for rect in rectangles)\n",
    "\n",
    "rectangles = [Rectangle(1, 2), Rectangle(3, 4)]\n",
    "print(sum_areas(rectangles))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако добавим нов клас `Square`, трябва да променим функцията, за да може да работи с новия клас."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List, Union\n",
    "\n",
    "class Rectangle:\n",
    "    def __init__(self, width, height):\n",
    "        self.width = width\n",
    "        self.height = height\n",
    "\n",
    "class Square:\n",
    "    def __init__(self, width):\n",
    "        self.width = width\n",
    "\n",
    "\n",
    "def sum_areas(items: Union[List[Rectangle], List[Square]]):\n",
    "    if isinstance(items[0], Square):\n",
    "        return sum(square.width * square.width for square in items)\n",
    "    elif isinstance(items[0], Rectangle):\n",
    "        return sum(rect.width * rect.height for rect in items)\n",
    "    else:\n",
    "        return 0\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Правилният подход тук е да създадем нов клас `Shape`, който да има метод `area`, и да променим функцията да работи с обекти от тип `Shape`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC\n",
    "from typing import List, Union\n",
    "\n",
    "class Shape(ABC):\n",
    "    def area(self) -> int:\n",
    "        pass\n",
    "\n",
    "class Rectangle(Shape):\n",
    "    def __init__(self, width, height):\n",
    "        self.width = width\n",
    "        self.height = height\n",
    "\n",
    "    def area(self):\n",
    "        return self.width * self.height\n",
    "\n",
    "class Square(Shape):\n",
    "    def __init__(self, width):\n",
    "        self.width = width\n",
    "\n",
    "    def area(self):\n",
    "        return self.width * self.width\n",
    "\n",
    "def sum_areas(items: List[Shape]):\n",
    "    return sum(item.area() for item in items)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Така вече, `sum_areas` е отворена за разширение (чрез добавяне на нови класове, които наследяват `Shape`), но затворена за модификация."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Liskov-substitution"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако потърсите в Wikipedia за Liskov substitution principle, може да видите следното: \n",
    "\n",
    "\"Нека $\\phi(x)$ е стойност, която е доказуема за обектите $x$ от тип $T$. Тогава $\\phi(y)$ трябва да е вярно за обекти $y$ от тип $S$, където $S$ е подтип на $T$.\" \n",
    "\n",
    "...\n",
    "\n",
    "Преведено на български, това означава, че ако имаме два класа `Base` и `Child`, навсякъде където използваме инстанции на `Base`, трябва да можем да ги заменим с инстанции на `Child`, и програмата ни да работи."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Нека разгледаме пример, в който този принцип не е спазен.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Rectangle area: 6\n"
     ]
    }
   ],
   "source": [
    "class Rectangle:\n",
    "    def __init__(self, x: int = 0, y: int = 0) -> None:\n",
    "        self.__x = x\n",
    "        self.__y = y\n",
    "    \n",
    "    @property\n",
    "    def x(self) -> int:\n",
    "        return self.__x\n",
    "    \n",
    "    @x.setter\n",
    "    def x(self, x: int) -> None:\n",
    "        self.__x = x\n",
    "\n",
    "    @property\n",
    "    def y(self) -> int:\n",
    "        return self.__y\n",
    "    \n",
    "    @y.setter\n",
    "    def y(self, y: int) -> None:\n",
    "        self.__y = y\n",
    "\n",
    "    def area(self) -> int:\n",
    "        return self.__x * self.__y\n",
    "\n",
    "class Square(Rectangle):\n",
    "    def __init__(self, x: int) -> None:\n",
    "        super().__init__(x, x)\n",
    "\n",
    "rectangle = Square()\n",
    "rectangle.x = 2\n",
    "rectangle.y = 3\n",
    "print(f'Rectangle area: {rectangle.area()}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако в този код заместим `Rectangle` с `Square`, програмата няма да работи по същия начин. Това е пример за нарушаване на LSP. Методите на `Rectangle` са по-общи от методите на `Square`, и не всички обекти от тип `Square` са обекти от тип `Rectangle`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Base:\n",
    "    def foo(self, a):\n",
    "        pass\n",
    "\n",
    "class Child(Base):\n",
    "    def foo(self, a, b):\n",
    "        pass\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interface segregation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Interface segregration принципа гласи \"много специфични интерфейси са по-добри от един общ интерфейс\". Това означава, че ако имаме два класа, които имат общ интерфейс, но само един от класовете го използва, то е по-добре да има два интерфейса, по един за всеки клас.\n",
    "\n",
    "Това означава, че ако имаме даден интерфейс, който има 10 метода, но само 2 от тях се използват от класовете, които го имплементират, то е по-добре да има два интерфейса, по един за всеки клас, и да имплементирате само тези 2 метода.\n",
    "\n",
    "Въпреки, че в Python няма интерфейси, този принцип е валиден. Нека разгледаме пример, в който този принцип не е спазен."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC\n",
    "\n",
    "class Camera(ABC):\n",
    "    def __init__(self, name: str, resolution: str) -> None:\n",
    "        self.__name = name\n",
    "        self.__resolution = resolution\n",
    "    \n",
    "    @property\n",
    "    def name(self) -> str:\n",
    "        return self.__name\n",
    "    \n",
    "    @name.setter\n",
    "    def name(self, name: str) -> None:\n",
    "        self.__name = name\n",
    "\n",
    "    @property\n",
    "    def resolution(self) -> str:\n",
    "        return self.__resolution\n",
    "    \n",
    "    @resolution.setter\n",
    "    def resolution(self, resolution: str) -> None:\n",
    "        self.__resolution = resolution\n",
    "\n",
    "    def take_photo(self) -> None:\n",
    "        pass\n",
    "    \n",
    "    def take_video(self) -> None:\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тук имаме два метода - `take_photo` и `take_video` - които биха се използвали от бъдещи `Camera` и `VideoCamera` класове. Това е пример за нарушаване на ISP, защото `Camera` не използва `take_video`, и `VideoCamera` не използва `take_photo`. Това означава, че `Camera` и `VideoCamera` не трябва да имплементират `CameraInterface`, а трябва да имат по един интерфейс, който да има само един метод - `take_photo` или `take_video`. Допълнително, можем да направим трети интерфейс - `Device`, който да държи общите данни и методи за тези устройства."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC\n",
    "\n",
    "class Device(ABC):\n",
    "    def __init__(self, name: str, resolution: str) -> None:\n",
    "        self.__name = name\n",
    "        self.__resolution = resolution\n",
    "    \n",
    "    @property\n",
    "    def name(self) -> str:\n",
    "        return self.__name\n",
    "    \n",
    "    @name.setter\n",
    "    def name(self, name: str) -> None:\n",
    "        self.__name = name\n",
    "\n",
    "    @property\n",
    "    def resolution(self) -> str:\n",
    "        return self.__resolution\n",
    "    \n",
    "    @resolution.setter\n",
    "    def resolution(self, resolution: str) -> None:\n",
    "        self.__resolution = resolution\n",
    "\n",
    "class Photoable(ABC):\n",
    "    def take_photo(self) -> None:\n",
    "        pass\n",
    "\n",
    "class Videoable(ABC):\n",
    "    def take_video(self) -> None:\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dependency inversion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Принципът за инверсия на зависимостите казва, че модулите от високо ниво не трябва да зависят от модули от ниско ниво, а обратното. Интерфейсите трябва да зависят от конкретните имплементации, а не обратното."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Dependency inversion](https://upload.wikimedia.org/wikipedia/commons/9/96/Dependency_inversion.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Нека разгледаме следния пример: Имаме три класа - `Developer`, `Tester` и `ProjectcManager`. `Developer` и `Tester` имплементират `work` метод, а `ProjectManager` управлява тези инстанции."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Developer():\n",
    "    def work():\n",
    "        pass\n",
    "\n",
    "class Tester():\n",
    "    def work():\n",
    "        pass\n",
    "\n",
    "class ProjectManager():\n",
    "    def __init__(self) -> None:\n",
    "        self.employees = []\n",
    "\n",
    "    def add_developer(self, developer: Developer):\n",
    "        self.employees.append(developer)\n",
    "    \n",
    "    def add_tester(self, tester: Tester):\n",
    "        self.employees.append(tester)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тук `ProjectManager` зависи от `Developer` и `Tester`, което е нарушение на DIP. Това означава, че ако искаме да добавим нов клас, който да имплементира `work` метода, но не е `Developer` или `Tester`, то `ProjectManager` няма да може да го управлява. Това е проблем, защото `ProjectManager` не трябва да знае какви класове има в системата, а само да управлява тези, които имплементират `work` метода.\n",
    "\n",
    "Решението е да създадем интерфейс `Worker`, който да има само `work` метода. `Developer` и `Tester` ще имплементират `Worker`, а `ProjectManager` ще зависи от `Worker`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC\n",
    "\n",
    "class Worker(ABC):\n",
    "    def work(self) -> None:\n",
    "        pass\n",
    "\n",
    "class Developer(Worker):\n",
    "    def work(self) -> None:\n",
    "        print('Developer is working')\n",
    "\n",
    "class Tester(Worker):\n",
    "    def work(self) -> None:\n",
    "        print('Tester is working')\n",
    "\n",
    "class EmployeeService(abc.ABC):\n",
    "    @abstractmethod\n",
    "    def work(self, worker: Worker):\n",
    "        ...\n",
    "\n",
    "class EmployeeServiceImpl(EmployeeService):\\\n",
    "    ...\n",
    "\n",
    "class MockEmployeeService(EmployeeService):\n",
    "    ...\n",
    "\n",
    "class ProjectManager():\n",
    "    def __init__(self, service: EmployeeService) -> None:\n",
    "        self.employees = []\n",
    "        self.employee_service = service\n",
    "\n",
    "    def add_worker(self, worker: Worker):\n",
    "        self.employees.append(worker)\n",
    "\n",
    "    def manage(self) -> None:\n",
    "        for employee in self.employees:\n",
    "            employee_service.work(employee)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Clean code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Освен SOLID принципите, съществуват и някои други правила, които спомагат за това нашия код да е четим и лесен за поддържане."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Meaningful Names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Както споменахме в началото, в работна среда по-често ще ни се налага да четем код, отколкото да пишем. Затова доброто именуване на всички единици от кода е от изключителна важност.\n",
    "\n",
    "Ще разгледаме няколко примера за добро и лошо именуване на променливи, функции и класове."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Point:\n",
    "    def __init__(self, x: int = 0, y: int = 0) -> None:\n",
    "        self.__x = x\n",
    "        self.__y = y\n",
    "    \n",
    "    @property\n",
    "    def x(self) -> int:\n",
    "        return self.__x\n",
    "    \n",
    "    @x.setter\n",
    "    def x(self, x: int) -> None:\n",
    "        self.__x = x\n",
    "    \n",
    "    @property\n",
    "    def y(self) -> int:\n",
    "        return self.__y\n",
    "    \n",
    "    @y.setter\n",
    "    def y(self, y: int) -> None:\n",
    "        self.__y = y\n",
    "    \n",
    "    def dist(self, p2: 'Point') -> float:\n",
    "        return ((self.__x - p2.x) ** 2 + (self.__y - p2.y) ** 2) ** 0.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тук основния заподозрян е метода `dist`. Първото нещо, което можем да направим, е да променим името на `distance_to_point`. Второто нещо, което можем да променим, е името на аргумент - вместо `p2`, може да се казва `other` или `target`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Името на променлива/функция/клас трябва да е максимално информативно и минимално кратко. В него не трябва да се съдържат някакви съкращения, освен ако не са много популярни. Например, `id` е много популярно съкращение, което се използва във всички езици, но `id` не е много информативно. Вместо това, може да се използва `identifier`.\n",
    "\n",
    "При булевите променливи и функциите които връщат булева стойност, трябва да започват с `is`, `has`, `can`, `should`, `will` или `did`. Другите функции трябва да бъдат именувани като глаголи, а класовете се именуват като съществителни.\n",
    "\n",
    "Имената трябва да могат да бъдат лесно четими, но и лесно произнасяеми - например `string_compare` е по-добро име от `strcmp`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Някои допълнителни насоки за писането на функции:\n",
    "\n",
    "  - Не трябва да има повече от 3 аргумента на функция. Ако има повече, трябва да се използва обект, който да съдържа всички аргументи.\n",
    "  - Функцията трябва да прави само едно нещо. Ако прави повече, трябва да се раздели на няколко функции.\n",
    "  - Функцията трябва да има единственно предназначение. Ако може да се използва за различни неща, трябва да се раздели на няколко функции.\n",
    "  - Избягвайте страничните ефекти във функциите\n",
    "  - Функциите трябват да имат висок cohesion, но нисък coupling\n",
    "    - Cohesion - колко силно свързани са нещата, които правят функцията\n",
    "    - Coupling - колко силно свързани са функциите между си\n",
    "  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Коментарите трябва да са информативни и да се използват за обясняване на нещата, които не са ясни от кода. Те не трябва да повтарят кода, а да го допълват. Използвайте коментари, за да обясните неясните неща от кода - някой regex, някакъв алгоритъм, някакъв неочакван резултат и т.н. Може да се добави примерен вход и изход към функцията."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Силно препоръчително е използването на docstrings. В тях описваме на високо ниво какво прави функцията, кавки аргументи приема и какво връща. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def bfs(graph: List[List[int]], start=Point(0, 0), target=Point(0, 0)) -> int:\n",
    "    \"\"\"\n",
    "    Performs a breadth-first search on the given graph, starting at the given start position.\n",
    "    \n",
    "    :param graph: The graph to search.\n",
    "    :param start: The start position.\n",
    "    :param target: The target position.\n",
    "\n",
    "    :return: The shortest path length from the start position to the target position.\n",
    "    \"\"\"\n",
    "    queue = [(start, 0)]\n",
    "    map_bounds = (len(graph), len(graph[0]))\n",
    "    distances = {}\n",
    "\n",
    "    visited = set()\n",
    "    shortest_path = 1000000\n",
    "\n",
    "    while len(queue) > 0:\n",
    "        position, path = queue.pop(0)\n",
    "\n",
    "        if not is_position_inside(position, map_bounds) or position in visited:\n",
    "            continue\n",
    "\n",
    "        if position == target:\n",
    "            shortest_path = min(shortest_path, path)\n",
    "\n",
    "        visited.add(position)\n",
    "\n",
    "        for offset_x, offset_y in [(0, 1), (0, -1), (1, 0), (-1, 0)]:\n",
    "            next_position = Point(position.x + offset_x, position.y + offset_y)\n",
    "\n",
    "            if not is_position_inside(next_position, map_bounds):\n",
    "                continue\n",
    "\n",
    "            if heights[next_position.x][next_position.y] - heights[position.x][position.y] <= 1:\n",
    "                queue.append((next_position, path + 1))\n",
    "\n",
    "    return shortest_path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "При спазването на дадени стандарти, можем лесно да генерираме документация за нашия код. Например, в Python можем да използваме Sphinx, който генерира HTML документация от docstrings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PEP8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "PEP8 е стандарт за писане на Python код. Той съдържа правила за именуване на променливи, функции, класове, както и правила за писане на код. Той е създаден от Python Software Foundation и е съвместим с Python 2 и 3.\n",
    "\n",
    "Стандарта сам по себе си е доста голям, затова ще се спрем само на части от него."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Подредба на кода\n",
    "Индентацията трябва да е 4 интервала. Според PEP8, табулациите трябва да се използват само ако се пише код във файлове, които са съвместими със табулации. Във всички останали случаи трябва да се използват интервали. Максималният размера на реда трябва да е до 79 символа, докато коментарите и docstring-овете трябва да са ограничени до 72 знака."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "При пренасяне на код на нов ред, пренесеният ред трябва да е подравнен спрямо отварящи delimiter, или с допълнието на 4 интервала спрямо предишния ред."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "\n",
    "# Aligned with opening delimiter.\n",
    "foo = long_function_name(var_one, var_two,\n",
    "                         var_three, var_four)\n",
    "\n",
    "# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.\n",
    "def long_function_name(\n",
    "        var_one, var_two, var_three,\n",
    "        var_four):\n",
    "    print(var_one)\n",
    "\n",
    "# Hanging indents should add a level.\n",
    "foo = long_function_name(\n",
    "    var_one, var_two,\n",
    "    var_three, var_four)\n",
    "\n",
    "# Wrong:\n",
    "\n",
    "# Arguments on first line forbidden when not using vertical alignment.\n",
    "foo = long_function_name(var_one, var_two,\n",
    "    var_three, var_four)\n",
    "\n",
    "# Further indentation required as indentation is not distinguishable.\n",
    "def long_function_name(\n",
    "    var_one, var_two, var_three,\n",
    "    var_four):\n",
    "    print(var_one)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В PEP8 също пише, че новите редове трябва да са преди бинарните оператори:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Wrong:\n",
    "# operators sit far away from their operands\n",
    "income = (gross_wages +\n",
    "          taxable_interest +\n",
    "          (dividends - qualified_dividends) -\n",
    "          ira_deduction -\n",
    "          student_loan_interest)\n",
    "\n",
    "# Correct:\n",
    "# easy to match operators with operands\n",
    "income = (gross_wages\n",
    "          + taxable_interest\n",
    "          + (dividends - qualified_dividends)\n",
    "          - ira_deduction\n",
    "          - student_loan_interest)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Относно празните редове - функциите на високо ниво и класовете трябва да бъдат разделени с два празни реда, а функциите на ниско ниво и методите на класовете - с един празен ред."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import-ите трябва да бъдат на отделни редове и да са подредени в следния ред:\n",
    "\n",
    "  1. Стандартните модули от Python\n",
    "  2. Външни модули\n",
    "  3. Модули от текущия проект\n",
    "\n",
    "Между отделните групи може (а и е хубаво) да има празен ред."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "import os\n",
    "import sys\n",
    "\n",
    "# Wrong:\n",
    "import sys, os"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Кавички"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В Python няма разлика между единичните и двойните кавички - PEP8 не препоръчва използването на едните пред другите. Но важно е да се използват еднакви кавички в рамките на един файл/проект."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Празни места"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Избягвайте използванто на множество празни места в кода."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "spam(ham[1], {eggs: 2})\n",
    "\n",
    "# Wrong:\n",
    "spam( ham[ 1 ], { eggs: 2 } )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "foo = (0,)\n",
    "\n",
    "# Wrong:\n",
    "bar = (0, )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "if x == 4: print(x, y); x, y = y, x\n",
    "\n",
    "# Wrong:\n",
    "if x == 4 : print(x , y) ; x , y = y , x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]\n",
    "ham[lower:upper], ham[lower:upper:], ham[lower::step]\n",
    "ham[lower+offset : upper+offset]\n",
    "ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]\n",
    "ham[lower + offset : upper + offset]\n",
    "\n",
    "# Wrong:\n",
    "ham[lower + offset:upper + offset]\n",
    "ham[1: 9], ham[1 :9], ham[1:9 :3]\n",
    "ham[lower : : upper]\n",
    "ham[ : upper]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "spam(1)\n",
    "\n",
    "# Wrong:\n",
    "spam (1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "dct['key'] = lst[index]\n",
    "\n",
    "# Wrong:\n",
    "dct ['key'] = lst [index]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Correct:\n",
    "x = 1\n",
    "y = 2\n",
    "long_variable = 3\n",
    "\n",
    "# Wrong:\n",
    "x             = 1\n",
    "y             = 2\n",
    "long_variable = 3\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Именуване, част 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Класовете в Python следва да се именуват спрямо `CapWords` (или `PascalCase`) конвенцията.\n",
    "- Имената на променливите и функциите следва да се именуват спрямо `snake_case` конвенцията."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pylint"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pylint е инструмент, който проверява дали написания от нас код съотвества на PEP8 стандарта. Можем да го инсталираме чрез `pip install pylint`. Стартираме го чрез `pylint`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Пример"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Live coding demo, idea is WIP."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.8.10 64-bit",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "916dbcbb3f70747c44a77c7bcd40155683ae19c65e1c03b4aa3499c5328201f1"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}