commandments.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Commandments\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Supreme Committee for the Doctrine of Coding has ruled important Commandments you shall follow. \n",
    "\n",
    "If you accept their wise words, you shall become a true Python Jedi."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "**WARNING**:  if you don't follow the Commandments, you will end up in _Debugging Hell_!\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## I COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall write Python code**\n",
    "</div>\n",
    "\n",
    "Who does not writes Python code, does not learn Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## II COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**Whenever you insert a variable in a** `for` **cycle, such variables must be new**\n",
    "</div>\n",
    "\n",
    "If you defined the variable before, you shall not reintroduce it in a `for`, because doing so might bring confusion in the minds of the readers.\n",
    "\n",
    "So avoid such sins:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "i = 7\n",
    "for i in range(3):  # sin, you lose variable i\n",
    "    print(i)\n",
    "    \n",
    "print(i)   # prints 2 and not 7  !!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n",
      "3\n",
      "4\n",
      "4\n",
      "0\n",
      "1\n",
      "2\n",
      "3\n",
      "4\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "for i in range(2):      \n",
    "    \n",
    "    for i in  range(5):  # debugging hell, you lose the i of external cycle         \n",
    "        print(i)\n",
    "        \n",
    "    print(i)  # prints 4 !!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "def f(i):\n",
    "    for i in range(3): # sin, you lose parameter i\n",
    "        print(i)\n",
    "    \n",
    "    print(i)  # prints 2, not the 7 we passed!\n",
    "    \n",
    "f(7)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## III COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall never ever reassign function parameters**\n",
    "\n",
    "</div>\n",
    "\n",
    "Never perform any of these assignments, as you risk losing the parameter passed during function call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "666\n"
     ]
    }
   ],
   "source": [
    "def sin(my_int):\n",
    "    my_int = 666            # you lost the 5 passed from external call!\n",
    "    print(my_int)           # prints 666\n",
    "    \n",
    "x = 5\n",
    "sin(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Same reasoning can be applied to all other types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "def evil(my_string):\n",
    "    my_string = \"666\"          "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def disgrace(my_list):\n",
    "    my_list = [666]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "def delirium(my_dict):\n",
    "    my_dict = {\"evil\":666}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the sole case when you have composite parameters like lists or dictionaries, you can write like below IF AND ONLY IF the function description requires to MODIFY the internal elements of the parameter (like for example sorting a list in-place or changing the field of a dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[8, 5, 9]\n"
     ]
    }
   ],
   "source": [
    "# MODIFY my_list in some way\n",
    "def allowed(my_list):\n",
    "    my_list[2] = 9     # OK, function text requires it\n",
    "    \n",
    "outside = [8,5,7]\n",
    "allowed(outside)\n",
    "print(outside)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFY dictionary in some way\n",
    "def ok(dictionary):\n",
    "    dictionary[\"my field\"] = 5       # OK, function text requires it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# MODIFY instance in some way\n",
    "def fine(class_instance):\n",
    "    class_instance.my_field = 7   # OK, function text requires it"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On the other hand, if the function requires to RETURN a NEW object, you shall not fall into the temptation of modifying the input:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "# RETURN a NEW sorted list\n",
    "def pain(my_list):\n",
    "    my_list.sort()    # BAD, you are modifying the input list instead of creating a new one!\n",
    "    return my_list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "# RETURN a NEW list\n",
    "def crisis(my_list):\n",
    "    my_list[0] = 5    # BAD, as above\n",
    "    return my_list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "# RETURN a NEW dictionary\n",
    "def torment(my_dict):\n",
    "    my_dict['a'] = 6  # BAD, you are modifying the input dictionary instead of creating a new one!\n",
    "    return my_dict"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "# RETURN a NEW class instance\n",
    "def desperation(my_instance):\n",
    "    my_instance.my_field = 6  # BAD, you are modifying the input object \n",
    "                              #      instead of creating a new one!\n",
    "    return my_instance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## IV COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall never ever reassign values to function calls or methods**\n",
    "</div>\n",
    "\n",
    "\n",
    "_WRONG:_\n",
    "\n",
    "```python\n",
    "\n",
    "my_function() = 666\n",
    "my_function() = 'evil'\n",
    "my_function() = [666]\n",
    "\n",
    "```\n",
    "\n",
    "_CORRECT:_ \n",
    "\n",
    "\n",
    "```python\n",
    "x = 5\n",
    "y = my_fun()\n",
    "z = []\n",
    "z[0] = 7\n",
    "d = dict()\n",
    "d[\"a\"] = 6\n",
    "```\n",
    "\n",
    "Function calls like `my_function()` return calculations results and store them in a box in memory which is only created for the purposes of the call, and Python will not allow us to reuse it like it were a variabile.\n",
    "\n",
    "Whenever you see `name()` in the left part, it _cannot_ be followed by the equality sign `=` (but it can be followed by two equals sign `==` if you are doing a comparison)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## V COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall never ever redefine system functions**\n",
    "</div>\n",
    "\n",
    "Python has several system defined functions. For example `list` is a Python type: as such, you can use it for example as a function to convert some type to a list:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['c', 'i', 'a', 'o']"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(\"ciao\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you allow the forces of evil to take the best of you, you might be tempted to use reserved words like `list` as a variable for you own miserable purposes: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "list = ['my', 'pitiful', 'list']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python allows you to do so, but we do **not**, for the consequences are disastrous.\n",
    "\n",
    "For example, if you now attempt to use `list` for its intended purpose like casting to list, it won't work anymore:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "list(\"ciao\")\n",
    "```\n",
    "```\n",
    "---------------------------------------------------------------------------\n",
    "TypeError                                 Traceback (most recent call last)\n",
    "<ipython-input-4-c63add832213> in <module>()\n",
    "----> 1 list(\"ciao\")\n",
    "\n",
    "TypeError: 'list' object is not callable\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In particular, we recommend to **not redefine** these precious functions:\n",
    "\n",
    "* `bool`, `int`,`float`,`tuple`,`str`,`list`,`set`,`dict`\n",
    "* `max`, `min`, `sum`\n",
    "* `next`, `iter`\n",
    "* `id`, `dir`, `vars`,`help`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## VI COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall use** `return` **command only if you see written RETURN in function description!**\n",
    "</div>\n",
    "\n",
    "If there is no `return` in function description, the function is intended to return `None`. In this case you don't even need to write `return None`, as Python will do it implicitly for you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## VII COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall also write on paper!**\n",
    "</div>\n",
    "\n",
    "If staring at the monitor doesn't work, help yourself and draw a representation of the state sof the program. \n",
    "Tables, nodes, arrows, all can help figuring out a solution for the problem. \n",
    "<br/>\n",
    "<br/>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## VIII COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**You shall never ever reassing** `self` **!**    \n",
    "</div>\n",
    "\n",
    "Never write horrors such as this:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyClass:\n",
    "    def my_method(self):\n",
    "        self = {'my_field':666}    # SIN"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since `self` is a kind of a dictionary, you might be tempted to write like above, but to external world it will bring no effect. \n",
    "\n",
    "For example, let's suppose somebody from outside makes a call like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "mc = MyClass()\n",
    "mc.my_method()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After the call `mc` will not point to `{'my_field':666}`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<__main__.MyClass at 0x7f4d9423b210>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and will not have `my_field`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "mc.my_field\n",
    "---------------------------------------------------------------------------\n",
    "AttributeError                            Traceback (most recent call last)\n",
    "<ipython-input-26-5c4e6630908d> in <module>()\n",
    "----> 1 mc.my_field\n",
    "\n",
    "AttributeError: 'MyClass' object has no attribute 'my_field'\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Following the same reasoning, you shall never reassign `self` to lists or others things:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyClass:\n",
    "    def my_method(self):\n",
    "        self = ['evil']     # YET ANOTHER SIN\n",
    "        self = 666          # NO NO NO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## IX COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall test!**\n",
    "</div>\n",
    "\n",
    "Untested code _does not work_ by definition. For ideas on how to test it, have a look at [Errors and testing](https://en.softpython.org/errors-and-testing/errors-and-testing-sol.ipynb)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## X COMMANDMENT\n",
    "\n",
    "<div class=\"jupman-alert-principle\"></div>\n",
    "<div class=\"alert alert-info\" >\n",
    "\n",
    "**You shall never ever add nor remove elements from a sequence you are iterating with a** `for` **!**\n",
    "</div>\n",
    "\n",
    "Falling into such temptations **would produce totally unpredictable behaviours** (do you know the expression _pulling the rug out from under your feet ?_ )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Do not add**, because you risk walking on a tapis roulant that never turns off:\n",
    "\n",
    "```python\n",
    "my_list = ['a','b','c','d','e']\n",
    "for el in my_list:\n",
    "    my_list.append(el)  # YOU ARE CLOGGING COMPUTER MEMORY\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Do not remove**, because you risk corrupting the natural order of things:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = ['a','b','c','d','e']\n",
    "\n",
    "for el in my_list:\n",
    "    my_list.remove(el)   # VERY BAD IDEA"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Look at the code. You think we removed eveything, uh?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['b', 'd']"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`O_o'` Do not even try to make sense of such sorcery - nobody can, because it is related to  Python internal implementation.\n",
    "\n",
    "Our version of Python gives this absurd result, yours may give another. Same applies for iteration on sets and dictionaries. **You are warned**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**If you really need to remove stuff from the sequence you are iterating on**, use a [while cycle](https://en.softpython.org/while/while1-sol.html) or first make a copy of the original sequence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.7.17"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}