module-2/coding-best-practies/coding_best_practices.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"./img/better-programmer.jpg\" style=\"height:400px\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Activation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "In the `code_examples` folder, you will see three inter-relating modules. Open the files, read them, and try to answer the following questions with a partner:\n",
    "- What are these modules doing? How do they fit together?\n",
    "- What did you find easy/hard about this other person's code?\n",
    "- What would have made it easier?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learning goals:\n",
    "- assess what makes code \"good\"\n",
    "- define python code standards\n",
    "- explore tools to help enforce good coding practices\n",
    "- use linters and vim in terminal to edit and improve code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Big outcome:\n",
    "Set you up to be super competitive in the job market and separate you from the chaff."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How is code assessed?\n",
    "\n",
    "> Given a particular problem (or student exercise), for example to compute the solution of an ordinary differential equation, there are a number of criteria that can be used to assess the computer program that solves the problem:\n",
    "\n",
    "> 1) **correctness**: does the code produce the correct answer? (For numerical problems, this requires some care: for the example of the differential equation, we would expect for a well-behaved differential equation that the numerical solution converges towards the exact solution as the step-width is reduced towards zero.) <br>\n",
    "> 2) **execution time performance**: how fast is the solution computed? <br>\n",
    "> 3) **memory consumption**: how much RAM is required to compute the solution? <br>\n",
    "> 4) **robustness?**: how robust is the implementation with respect to missing/incorrect input values, etc?<br>\n",
    "> 5) **elegance, readability, documentation**: how long is the code? Is it easy for others to understand? Is it easy to extend? Is it well documented, or is the choice of algorithm, data structures and naming of objects sufficient to document what it does?\n",
    "> - Hans Fangohr, Neil O’Brien, [paper here](https://arxiv.org/pdf/1509.03556.pdf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### elegance, readability, and documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Who is the audience for your code?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The importance of standards"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import this"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Two big questions:\n",
    "\n",
    "- What does this even mean in practical language?\n",
    "- Do I have to memorize a long list of standards?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### A lot of the \"Python Standards\" are common sense, let's go over some comparisons"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variable naming: which is more readable?\n",
    "\n",
    "Option 1:\n",
    "```\n",
    "x = 'John Smith'\n",
    "y, z = x.split()\n",
    "print(z, y, sep=', ')\n",
    "'Smith, John'\n",
    "```\n",
    "\n",
    "Option 2:\n",
    "```\n",
    "name = 'John Smith'\n",
    "first_name, last_name = name.split()\n",
    "print(last_name, first_name, sep=', ')\n",
    "'Smith, John'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function naming: which is better?\n",
    "\n",
    "Option 1:\n",
    "```\n",
    "def db(x):\n",
    "    return x * 2\n",
    "```\n",
    "\n",
    "Option 2:\n",
    "```\n",
    "def multiply_by_two(x):\n",
    "    return x * 2\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Line breaks & hanging indents\n",
    "\n",
    "Option 1:\n",
    "```\n",
    "var = function(\n",
    "    arg_one, arg_two,\n",
    "    arg_three, arg_four)\n",
    "```\n",
    "\n",
    "Option 2:\n",
    "```\n",
    "var = function(arg_one, arg_two,\n",
    "    arg_three, arg_four)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Functions and hanging indents\n",
    "\n",
    "Option 1:\n",
    "```\n",
    "def function(\n",
    "        arg_one, arg_two,\n",
    "        arg_three, arg_four):\n",
    "    return arg_one\n",
    "```\n",
    "\n",
    "Option 2:\n",
    "\n",
    "```\n",
    "def function(\n",
    "    arg_one, arg_two,\n",
    "    arg_three, arg_four):\n",
    "    return arg_one\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Line breaks with math\n",
    "\n",
    "Option 1:\n",
    "```\n",
    "total = (first_variable\n",
    "         + second_variable\n",
    "         - third_variable)\n",
    "```\n",
    "\n",
    "Option 2:\n",
    "```\n",
    "total = (first_variable +\n",
    "         second_variable -\n",
    "         third_variable)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### If statement sequences\n",
    "\n",
    "Option 1:\n",
    "```\n",
    "if not x is None:\n",
    "    return 'x exists!'\n",
    "```\n",
    "Option 2:\n",
    "```\n",
    "if x is not None:\n",
    "    return 'x exists!'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## But do we have to memorize?\n",
    "\n",
    "### No"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Lint\n",
    "![lint](img/lint2.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### History of lint\n",
    "> Stephen C. Johnson, a computer scientist at Bell Labs, came up with lint in 1978 while debugging the Yacc grammar he was writing for C and dealing with portability issues stemming from porting Unix to a 32-bit machine. The term \"lint\" was derived from the name of the undesirable bits of fiber and fluff found in sheep's wool. In 1979, lint was used outside of Bell Labs for the first time in the seventh version  of the Unix operating system. - [wikipedia source](https://en.wikipedia.org/wiki/Lint_(software))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Linters we will use:\n",
    "\n",
    "- [pycodestyle](https://pypi.org/project/pycodestyle/) - already comes with conda, do not need to re-install\n",
    "- [flake8](https://pypi.org/project/flake8/) - if you get a `disutils` error, run `pip install flake8 --ignore-installed`\n",
    "- [pep8-namig](https://pypi.org/project/pep8-naming/)\n",
    "- [pydocstyle](https://pypi.org/project/pydocstyle/)\n",
    "\n",
    "\n",
    "if we have time:\n",
    "- [pylint](https://pypi.org/project/pylint/)\n",
    "- [black](https://pypi.org/project/black/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python Enhancement Proposals (PEP)\n",
    "\n",
    "[Index of PEP](https://www.python.org/dev/peps/)\n",
    "\n",
    ">\"code is read much more often than it is written\" - Guido\n",
    "\n",
    "\n",
    "> 'Any fool can write code that a computer can understand. Good programmers write code that humans can understand.' - Martin Fowler\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[pep8 error codes](https://pep8.readthedocs.io/en/latest/intro.html#error-codes)\n",
    "\n",
    "Error Codes:\n",
    ">**E1s** : Indentation<br>\n",
    ">**E2s** : Whitespace<br>\n",
    ">**E3s** : Blank Lines<br>\n",
    ">**E4s** : Imports<br>\n",
    ">**E5s** : Line Lengths<br>\n",
    ">**E7s** : Statement<br>\n",
    ">**E9s** : Runtime\n",
    "\n",
    "Warning Codes:\n",
    ">**W1s** : Indentation warning <br>\n",
    ">**W2s** : Whitespace warning <br>\n",
    ">**W3s** : Blank Lines warning <br>\n",
    ">**W5s** : Line break warning <br>\n",
    ">**W6s** : Depreciation warning"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `pep8-naming`: naming conventions\n",
    "\n",
    "|**Type**  | **Naming Convention**  | **Example**  |\n",
    "|----------|------------------------|--------------|\n",
    "|Function | Use a lowercase word or words. Separate words by underscores to improve readability. | `function`,<br> `my_function` |\n",
    "|Variable | Use a lowercase single letter, word, or words. Separate words with underscores to improve readability. | `x`, `var`, `my_variable`|\n",
    "|Class | Start each word with a capital letter. Do not separate words with underscores. This style is called camel case. | `Model`, `MyClass` |\n",
    "|Method | Use a lowercase word or words. Separate words with underscores to improve readability. | \t`class_method`, `method`|\n",
    "|Constant | Use an uppercase single letter, word, or words. Separate words with underscores to improve readability.|`CONSTANT`,<br> `MY_CONSTANT`,<br> `MY_LONG_CONSTANT` |\n",
    "|Module | Use a short, lowercase word or words. Separate words with underscores to improve readability. | `module.py`,<br> `my_module.py`|\n",
    "|Package | Use a short, lowercase word or words. Do not separate words with underscores.| `package`,<br> `mypackage`|\n",
    "\n",
    "[heavily borrowed from real python](https://realpython.com/python-pep8/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Docstrings\n",
    "\n",
    "Adheres to the standards set forth in [pep-257](https://www.python.org/dev/peps/pep-0257/)\n",
    "\n",
    "Example of `pydocstyle` output:\n",
    "\n",
    "```\n",
    "$ pydocstyle test.py\n",
    "test.py:18 in private nested class `meta`:\n",
    "        D101: Docstring missing\n",
    "test.py:27 in public function `get_user`:\n",
    "    D300: Use \"\"\"triple double quotes\"\"\" (found '''-quotes)\n",
    "test:75 in public function `init_database`:\n",
    "    D201: No blank lines allowed before function docstring (found 1)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Let's get linting!\n",
    "\n",
    "For this section we will work from the terminal. You may want to have more than one terminal window open.\n",
    "\n",
    "We will be using `vim` to edit `.py` files. This is for practice. With increased usage comes increased comfort.\n",
    "\n",
    "Let's start with:\n",
    "\n",
    ">`pycodestyle test.py`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(follow along in terminal and refer to video later as a reference)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Linters are not infallible \n",
    "\n",
    "Let's look at `test2.py` using our linters\n",
    "\n",
    "Run the following command in terminal:\n",
    ">`flake8 test2.py`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also test `test3.py` in the same way:\n",
    ">`flake8 test3.py`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then compare what `plynt` catches vs `flake8` on `test3.py`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Your task:\n",
    "\n",
    "- use `vim` with `flake8`, `pydocstyle`, and `pylint` to edit the sample `.py` files until no errors return from the linters\n",
    "- take a screen shot of all three files being linted and returning *nothing*\n",
    "- send that screen shot to coaches and instructor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![meme](img/pep8_meme.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Moving forward\n",
    "\n",
    "We will be linting your code using `flake8`, `pylint`, and `pydocstyle`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A good follow up resource:\n",
    "[Top 10 coding mistakes made by data scientists](https://towardsdatascience.com/top-10-coding-mistakes-made-by-data-scientists-bb5bc82faaee)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}