python-intro/solutions/ex15_programming_style.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "a1c76d0e-1029-42fe-96b4-7e8fb88eb414",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "# Exercise 15: Programming Style"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d78ecfe9-ac90-422f-b746-7e67e0ca6b23",
   "metadata": {},
   "source": [
    "## Aim: Write readable and well-styled code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80ff54d7-cd4a-42ba-bf9d-c89eb4b71eba",
   "metadata": {},
   "source": [
    "### Issues covered:\n",
    "- Adding comments\n",
    "- Using sensible variable names\n",
    "- Using the correct indentation\n",
    "- Using `assertion errors` to check function arguments\n",
    "- Using docstrings and multiline strings to describe functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8417d73f-eed3-451b-8af9-a2a656516be3",
   "metadata": {},
   "source": [
    "## 1. Let's add some comments to the code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae640e64-72e6-42c6-9dc5-a629335d420e",
   "metadata": {},
   "source": [
    "Add some comments to the block below to describe what the code is doing.\n",
    "```\n",
    "i = 0\n",
    "for number in range(100):\n",
    "  i = i + number\n",
    "print(i)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d50191b6-94b9-42c3-bc75-14626387703b",
   "metadata": {
    "editable": true,
    "execution": {
     "iopub.execute_input": "2023-10-23T10:34:43.881126Z",
     "iopub.status.busy": "2023-10-23T10:34:43.880448Z",
     "iopub.status.idle": "2023-10-23T10:34:43.896092Z",
     "shell.execute_reply": "2023-10-23T10:34:43.894941Z"
    },
    "slideshow": {
     "slide_type": ""
    },
    "tags": [
     "clear_answer_cell"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "4950\n"
     ]
    }
   ],
   "source": [
    "# Initialise the counter to \n",
    "i = 0\n",
    "for number in range(100):\n",
    "  i = i + number\n",
    "print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a2f463c-38ae-4c8c-b46a-72e5c3a677b1",
   "metadata": {},
   "source": [
    "## 2. Let's take a look at formatting"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a481223-40cf-4092-aad5-c7154ac5e865",
   "metadata": {},
   "source": [
    "The block of code below features some very unhelpful variable names and some bad indentation. Rename them to something useful and sort the formatting.\n",
    "```\n",
    "a = 'March'\n",
    "  b = 19\n",
    "    c = 1998\n",
    "    def d(e, f, g):\n",
    "       h = \"My birthday is: \" + e + \" \" + str(f) + \" \" + str(g)\n",
    "    return h\n",
    "g = d(a, b, c)\n",
    "       print(g)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "3cc051d8-99b4-4af4-8d3c-fe970e2683ac",
   "metadata": {
    "editable": true,
    "execution": {
     "iopub.execute_input": "2023-10-23T10:34:43.902112Z",
     "iopub.status.busy": "2023-10-23T10:34:43.901081Z",
     "iopub.status.idle": "2023-10-23T10:34:43.915571Z",
     "shell.execute_reply": "2023-10-23T10:34:43.914583Z"
    },
    "slideshow": {
     "slide_type": ""
    },
    "tags": [
     "clear_answer_cell"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "My birthday is: March 19 1998\n"
     ]
    }
   ],
   "source": [
    "birth_month = 'March'\n",
    "birth_date = 19\n",
    "birth_year = 1998\n",
    "def birthday_message(month, date, year):\n",
    "    birthday_string = \"My birthday is: \" + month + \" \" + str(date) + \" \" + str(year)\n",
    "    return birthday_string\n",
    "my_birthday = birthday_message(birth_month, birth_date, birth_year)\n",
    "print(my_birthday)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42008010-402d-4058-b20d-1fa0592640f3",
   "metadata": {},
   "source": [
    "## 3. Let's add an `assertion error` to check the function arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5644fac6-4828-41d0-9974-e3e1bf9ad214",
   "metadata": {},
   "source": [
    "How can we ensure that negative numbers aren't passed to the following function? Add in a line of code to turn the ValueError into a different type of error.\n",
    "```\n",
    "import math\n",
    "def calculate_log(number):\n",
    "    log = math.log(number)\n",
    "    return log\n",
    "print(calculate_log(-1))\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "f8cba5be-ead0-4947-8fed-01e45f6f720d",
   "metadata": {
    "editable": true,
    "execution": {
     "iopub.execute_input": "2023-10-23T10:34:43.921889Z",
     "iopub.status.busy": "2023-10-23T10:34:43.921277Z",
     "iopub.status.idle": "2023-10-23T10:34:44.329526Z",
     "shell.execute_reply": "2023-10-23T10:34:44.328865Z"
    },
    "slideshow": {
     "slide_type": ""
    },
    "tags": [
     "clear_answer_cell",
     "allow_errors"
    ]
   },
   "outputs": [
    {
     "ename": "AssertionError",
     "evalue": "",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "Input \u001b[0;32mIn [3]\u001b[0m, in \u001b[0;36m<cell line: 6>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      4\u001b[0m     log \u001b[38;5;241m=\u001b[39m math\u001b[38;5;241m.\u001b[39mlog(number)\n\u001b[1;32m      5\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m log\n\u001b[0;32m----> 6\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[43mcalculate_log\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m-\u001b[39;49m\u001b[38;5;241;43m1\u001b[39;49m\u001b[43m)\u001b[49m)\n",
      "Input \u001b[0;32mIn [3]\u001b[0m, in \u001b[0;36mcalculate_log\u001b[0;34m(number)\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mcalculate_log\u001b[39m(number):\n\u001b[0;32m----> 3\u001b[0m     \u001b[38;5;28;01massert\u001b[39;00m number \u001b[38;5;241m>\u001b[39m \u001b[38;5;241m0\u001b[39m\n\u001b[1;32m      4\u001b[0m     log \u001b[38;5;241m=\u001b[39m math\u001b[38;5;241m.\u001b[39mlog(number)\n\u001b[1;32m      5\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m log\n",
      "\u001b[0;31mAssertionError\u001b[0m: "
     ]
    }
   ],
   "source": [
    "import math\n",
    "def calculate_log(number):\n",
    "    assert number > 0\n",
    "    log = math.log(number)\n",
    "    return log\n",
    "print(calculate_log(-1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "624df7db-501a-42c2-892e-5feea092d0c0",
   "metadata": {},
   "source": [
    "## 4. Let's add a description of our function."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31b55609-5d16-4137-9b2e-3d7884756e71",
   "metadata": {},
   "source": [
    "Add a docstring for the following function, then check that help(random_number) returns your docstring.\n",
    "```\n",
    "import random\n",
    "def random_number(lower, upper):\n",
    "    return random.randint(lower, upper)\n",
    "random_number(1,100)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "07df1934-36c7-49d1-b95f-3e310baaebcc",
   "metadata": {
    "editable": true,
    "execution": {
     "iopub.execute_input": "2023-10-23T10:34:44.332973Z",
     "iopub.status.busy": "2023-10-23T10:34:44.332768Z",
     "iopub.status.idle": "2023-10-23T10:34:44.338303Z",
     "shell.execute_reply": "2023-10-23T10:34:44.337695Z"
    },
    "slideshow": {
     "slide_type": ""
    },
    "tags": [
     "clear_answer_cell"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function random_number in module __main__:\n",
      "\n",
      "random_number(lower, upper)\n",
      "    A function to generate a random number between the lower and upper values given.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import random\n",
    "def random_number(lower, upper):\n",
    "    \"A function to generate a random number between the lower and upper values given.\"\n",
    "    return random.randint(lower, upper)\n",
    "random_number(1,100)\n",
    "help(random_number)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2361c9b1-c114-4ef8-8d84-6313255dedd3",
   "metadata": {},
   "source": [
    "Add an extra line to your docstring, making it a multiline string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "53a43e3c-94df-4b92-80d4-bae918718f49",
   "metadata": {
    "editable": true,
    "execution": {
     "iopub.execute_input": "2023-10-23T10:34:44.341481Z",
     "iopub.status.busy": "2023-10-23T10:34:44.341284Z",
     "iopub.status.idle": "2023-10-23T10:34:44.348073Z",
     "shell.execute_reply": "2023-10-23T10:34:44.347476Z"
    },
    "slideshow": {
     "slide_type": ""
    },
    "tags": [
     "clear_answer_cell"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function random_number in module __main__:\n",
      "\n",
      "random_number(lower, upper)\n",
      "    A function to generate a random number between the lower and upper values given.\n",
      "    Integers only.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import random\n",
    "def random_number(lower, upper):\n",
    "    \"\"\"\n",
    "    A function to generate a random number between the lower and upper values given.\n",
    "    Integers only.\n",
    "    \"\"\"\n",
    "    return random.randint(lower, upper)\n",
    "random_number(1,100)\n",
    "help(random_number)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 + Jaspy",
   "language": "python",
   "name": "jaspy"
  },
  "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.10.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}