13-Documentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# Code Style & Documentation\n",
    "\n",
    "- readability\n",
    "- code style\n",
    "- PEP8\n",
    "- comments\n",
    "- documentation\n",
    "- linters\n",
    "- versioning"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Code Readability (API)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "\"Code is more often read than written\" - Guido van Rossum"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "So: code should be written to be readable by humans."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Note: one of those humans is future you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## The Zen of Python"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "import this"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Writing Readable Code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "So how do we write good code for humans?\n",
    "\n",
    "- Use good structure\n",
    "- Use good naming\n",
    "- Use code comments and include documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Good Structure\n",
    "\n",
    "If you design your program using separate functions for each task, avoid copying + pasting (functions and loops instead), and consider structure beforehand, you'll be set up for success"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Good Naming\n",
    "\n",
    "Clear names are for humans. The computer doesn't care, but you and others reading your code do."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Code comments & Documentation\n",
    "\n",
    "Helpful comments and documentation take your code to the next level. The final piece in the trifecta of readable code! "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Good code has good documentation - but code documentation should _not_ be used to try and fix unclear names, or bad structure. \n",
    "\n",
    "Rather, comments should add any additional context and information that helps explain what the code is, how it works, and why it works that way. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "source": [
    "These will all be components of your final project grade."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "#### Clicker Question #1\n",
    "\n",
    "What does the following code do?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "scrolled": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "def ff(jj):\n",
    "    oo = list(); jj = list(jj) \n",
    "    for ii in jj: oo.append(str(ord(ii)))\n",
    "    return '+'.join(oo)\n",
    "ff('Hello World.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- A) Returns unicode code points, as a list\n",
    "- B) Encodes a string as a cypher, returning a string of alphabetical characters\n",
    "- C) Returns unicode code points, as a string\n",
    "- D) Encodes inputs alphabetical characters, returned as a list\n",
    "- E) This code will fail"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Improvement Considerations:\n",
    "- Structural considerations: indentations & spacing\n",
    "- Improved naming: functions & variables\n",
    "- Add Comments within code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def return_unicode(input_list):\n",
    "    string = list()\n",
    "    input_list = list(input_list)\n",
    "      \n",
    "    for character in input_list: \n",
    "        string.append(str(ord(character)))\n",
    "        \n",
    "    output_string = '+'.join(string)\n",
    "    return output_string\n",
    "\n",
    "return_unicode('Hello World.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- A) Returns unicode code points, as a list\n",
    "- B) Encodes a string as a cypher, returning a string of alphabetical characters\n",
    "- C) Returns unicode code points, as a string\n",
    "- D) Encodes inputs alphabetical characters, returned as a list\n",
    "- E) This code will fail"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Improvement Considerations:\n",
    "- Structural considerations: indentations & spacing\n",
    "- Improved naming: functions & variables\n",
    "- Add Comments within code\n",
    "- **Proper Documentation!**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# Let's fix this code!\n",
    "def convert_to_unicode(input_string):\n",
    "    \"\"\"Converts an input string into a string containing the unicode code points.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    input_string : string\n",
    "        String to convert to code points\n",
    "        \n",
    "    Returns\n",
    "    -------\n",
    "    output_string : string\n",
    "        String containing the code points for the input string.\n",
    "    \"\"\" \n",
    "    \n",
    "    output = list()\n",
    "    # Converting a string to a list, to split up the characters of the string\n",
    "    input_list = list(input_string)\n",
    "    \n",
    "    for character in input_list:   \n",
    "        temp = ord(character)\n",
    "        output.append(temp)\n",
    "\n",
    "    output_string = '+'.join(output)\n",
    "        \n",
    "    return output_string"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Code Style"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Or: How to be Pythonic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Reasons to be Pythonic:\n",
    "- user friendly for humans\n",
    "- extra work up-front on the developers (pays off on the long run)\n",
    "- best to practice this early on (I promise!)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Style Guides"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Coding style refers to a set of conventions for how to write good code. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Consistency is the goal. Rules help us achieve consistency."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Much of this will apply to other programming languages, so it's good to learn...regardless of language.\n",
    "\n",
    "Some of these Code Style notes will be more specific to Python, however."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Python Enhancement Proposals (PEPs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Python PEPs are proposals for how something should be / work in the Python programming language. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "These are written by the people responsible for the Python Programming language."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "PEP are voted on before incorporation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### PEP8"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<b><a href=\"https://www.python.org/dev/peps/pep-0008/\">PEP8</a></b> is an accepted proposal that outlines the style guide for Python.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Defines the style guide for Pythonistas (people who code in Python)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Code Style: Structure\n",
    "\n",
    "- blank lines\n",
    "- indentaion\n",
    "- spacing \n",
    "- length <- NEW\n",
    "- imports <- NEW"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "### Blank Lines\n",
    "\n",
    "- Use 2 blank lines between functions & classes, and 1 between methods\n",
    "- Use 1 blank line between segments to indicate logical structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "### Indentation\n",
    "\n",
    "Use spaces to indicate indentation levels, with each level defined as 4 spaces. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "### Spacing\n",
    "\n",
    "- Put one (and only one) space between each element\n",
    "- Index and assignment don't have a space between opening & closing '()' or '[]'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Line Length (NEW)\n",
    "\n",
    "- PEP8 recommends that each line be at most 79 characters long"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Computers used to require this.\n",
    "\n",
    "But, super long lines are hard to read at a glance."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Multi-Line"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "my_long_list = [1, 2, 3, 4, 5, \n",
    "                6, 7, 8, 9, 10]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Note: you can explicitly indicate a new line with '\\'\n",
    "my_string = 'Python is ' + \\\n",
    "            'a pretty great language.'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### One Statement Per Line (NEW-ish)\n",
    "\n",
    "- While you *can* condense multiple statements into one line, you usually shouldn't."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Badness\n",
    "for i in [1, 2, 3]: print(i**2 + i%2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Goodness\n",
    "for i in [1, 2, 3]:\n",
    "    print(i**2 + i%2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Imports\n",
    "\n",
    "- Import one module per line\n",
    "- Avoid `*` imports\n",
    "- Use the import order: standard library; 3rd party packages; local / custom code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Badness\n",
    "from numpy import *\n",
    "\n",
    "import os, sys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Goodness\n",
    "import os\n",
    "import sys\n",
    "\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Note: If you don't know how to import a local/custom module, figure that out this week in Coding Lab or office hours."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Specific Guidelines - Naming (review)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "### Valid Names\n",
    "\n",
    "- Use descriptive names for all modules, variables, functions and classes, that are longer than 1 character"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "### Naming Style\n",
    "\n",
    "- CapWords (leading capitals, no separation) for Classes\n",
    "- snake_case (all lowercase, underscore separator) for variables, functions, and modules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Code Documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Code documentation is text that accompanies and/or is embedded within a software project, that explains what the code is and how to use it. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Stuff written for humans in human language to help the humans."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Code Comments vs. Documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Comments are string literals written directly in the code, typically directed at developers - people reading and potentially writing the code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Documentation are descriptions and guides written for code users. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Inline Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Code comments should use `#`, and be written at the same indentation level of the code it describes. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "How to use comments:\n",
    "- Generally:\n",
    "    - focus on the *how* and *why*, over literal 'what is the code'\n",
    "    - explain any context needed to understand the task at hand\n",
    "    - give a broad overview of what approach you are taking to perform the task\n",
    "    - if you're using any unusual approaches, explain what they are, and why you're using them\n",
    "- Comments need to be maintained - make sure to keep them up to date"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Bad Comments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# This is a loop that iterates over elements in a list\n",
    "for element in list_of_elements:\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Good Comments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Because of X, we will use approach Y to do Z\n",
    "for element in list_of_elements:\n",
    "    # comment for code block\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Code Style: Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Out-of-date comments are worse than no comments at all.\n",
    "\n",
    "Keep your comments up-to-date."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Block comments\n",
    "- apply to some (or all) code that follows them\n",
    "- are indented to the same level as that code. \n",
    "- Each line of a block comment starts with a # and a single space"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Badness\n",
    "import random\n",
    "\n",
    "def week_9():\n",
    "# help try to destress students by picking one thing from the following list using random\n",
    "    statements = [\"You've totally got this!\",\"You're so close!\",\"You're going to do great!\",\"Remember to take breaks!\",\"Sleep, water, and food are really important!\"]\n",
    "    out = random.choice(statements)\n",
    "    return out\n",
    "\n",
    "week_9()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Goodness\n",
    "def week_9():\n",
    "    \n",
    "    # Randomly pick from list of de-stressing statements\n",
    "    # to help students as they finish the quarter.\n",
    "    statements = [\"You've totally got this!\", \n",
    "                  \"You're so close!\", \n",
    "                  \"You're going to do great!\",\n",
    "                  \"Remember to take breaks!\",\n",
    "                  \"Sleep, water, and food are really important!\"]\n",
    "    \n",
    "    out = random.choice(statements)\n",
    "    \n",
    "    return out\n",
    "\n",
    "week_9()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Inline comments\n",
    "- to be used sparingly\n",
    "- to be separated by at least two spaces from the statement\n",
    "- start with a # and a single space"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Badness\n",
    "week_9()#words of encouragement"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Goodness\n",
    "week_9()  # words of encouragement"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "<b>Docstrings</b> are in-code text that describe modules, classes and functions. They describe the operation of the code.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Numpy style docs\n",
    "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html) are a particular specification for docstrings. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Example Docstring"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def add(num1, num2):\n",
    "    \"\"\"Add two numbers together. \n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    num1 : int or float\n",
    "        The first number, to be added. \n",
    "    num2 : int or float\n",
    "        The second number, to be added.\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    answer : float\n",
    "        The result of the addition. \n",
    "    \"\"\"\n",
    "    \n",
    "    answer = num1 + num2\n",
    "    \n",
    "    return answer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Docstrings\n",
    "\n",
    "- multi-line string that describes what's going on\n",
    "- starts and ends with triple quotes `\"\"\"`\n",
    "- one sentence overview at the top - the task/goal of function\n",
    "- **Parameters** : description of function arguments, keywords & respective types\n",
    "- **Returns** : explanation of returned values and their types"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**Docstrings** are available to you *outside* of the source code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "source": [
    "Note: ChatGPT is pretty good at generating docstrings..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Docstrings are available through the code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "add?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# The `help` function prints out the `docstring` \n",
    "# of an object (module, function, class)\n",
    "help(add)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### `__doc__`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "# Docstrings get stored as the `__doc__` attribute\n",
    "# can also be accessed from there\n",
    "print(add.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Clicker Question #2\n",
    "\n",
    "What should be included in a docstring?\n",
    "\n",
    "1) Input arguments and their types  \n",
    "2) A brief overview sentence about the code  \n",
    "3) A copy of the `def` line  \n",
    "4) Returned variables and their types  \n",
    "5) A step by step description of the procedure used in the code  \n",
    "\n",
    "- A) 1, 4 \n",
    "- B) 2, 3, 5\n",
    "- C) 3, 5 \n",
    "- D) 1, 2, 4 \n",
    "- E) 1, 2, 3, 4, 5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Projects & Documentation\n",
    "\n",
    "**Do *all* of my functions need `numpy` documentation?**\n",
    "\n",
    "1. Your original code definitely needs `numpy` docstrings (required)\n",
    "2. It's best if all your main functions have docstrings (optional)\n",
    "    - If you include functions from an assignment, go ahead document them\n",
    "    - If you write a teeny tiny function to accomplish a super small task, no need to document"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Documentation for a Software Project"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Documentation Files:\n",
    "- A `README` is a file that provides an overview of the project to potential users and developers\n",
    "- A `LICENSE` file specifies the license under which the code is available (the terms of use)\n",
    "- An `API Reference` is a collection of the docstrings, listing public interfaces, parameters and return values\n",
    "- Tutorials and/or Examples show examples and tutorials for using the codebase"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Documentation Sites"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Documentation sites are a host of a package's documentation, for code users. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Example: Function Documentation\n",
    "`numpy.array` :\n",
    "https://docs.scipy.org/doc/numpy/reference/generated/numpy.array.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "#### Example: Package Documentation\n",
    "**scikit learn** (`sklearn`) : https://scikit-learn.org/stable/index.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Linters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<div class=\"alert alert-success\">\n",
    "A linter is a tool that analyzes code for both programmatic errors and stylistic issues. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "`pylint` is available from Anaconda to check this for you. (Not available on datahub.)\n",
    "\n",
    "\n",
    "```python\n",
    "# to install on datahub\n",
    "!pip install --user pylint\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Clicker Question #3\n",
    "\n",
    "How many PEP8 violations can you find in this code?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def MyFunction(input_num):\n",
    "    \n",
    "    my_list = [0,1,2,3]\n",
    "    if 1 in my_list: ind = 1\n",
    "    else:\n",
    "      ind = 0\n",
    "    qq = []\n",
    "    for i in my_list [ind:]:\n",
    "        qq.append(input_num/i)\n",
    "    return qq"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- A) None\n",
    "- B) 1 or 2 \n",
    "- C) 3 or 4 \n",
    "- D) 5 or 6\n",
    "- E) 7 or more"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "### list here\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# Let's fix this code\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# check using pylint\n",
    "!pylint linter_example.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Software Versioning\n",
    "\n",
    "When you make changes to the software you've released into the world, you have to change the version of that software to let people know changes have occurred."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Versioning Schemes\n",
    "\n",
    "The rules, if you're new to this can be [dizzying](https://www.python.org/dev/peps/pep-0440/#version-scheme), so we'll [simplify](https://www.python.org/dev/peps/pep-0396/) for now:\n",
    "\n",
    "- `<MAJOR>.<MINOR>`\n",
    "    - i.e. 1.3\n",
    "    \n",
    "- `<MAJOR>.<MINOR>.<MAINTENANCE>`\n",
    "    - i.e. 1.3.1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "- `<MAJOR>` - increase by 1 w/ incompatible API changes\n",
    "- `<MINOR>` - increase by 1 w/ added functionality in a backwards-compatible manner\n",
    "- `<MAINTENANCE>` - (aka patch) increase by 1 w/  backwards-compatible bug fixes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "# see version information\n",
    "import pandas as pd\n",
    "pd.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "In Python package development... when `<MAJOR>` == 0, suggests a package in development"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Name: pandas\n",
      "Version: 2.1.4\n",
      "Summary: Powerful data structures for data analysis, time series, and statistics\n",
      "Home-page: https://pandas.pydata.org\n",
      "Author: \n",
      "Author-email: The Pandas Development Team <pandas-dev@python.org>\n",
      "License: BSD 3-Clause License\n",
      "\n",
      "Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team\n",
      "All rights reserved.\n",
      "\n",
      "Copyright (c) 2011-2023, Open source contributors.\n",
      "\n",
      "Redistribution and use in source and binary forms, with or without\n",
      "modification, are permitted provided that the following conditions are met:\n",
      "\n",
      "* Redistributions of source code must retain the above copyright notice, this\n",
      "  list of conditions and the following disclaimer.\n",
      "\n",
      "* Redistributions in binary form must reproduce the above copyright notice,\n",
      "  this list of conditions and the following disclaimer in the documentation\n",
      "  and/or other materials provided with the distribution.\n",
      "\n",
      "* Neither the name of the copyright holder nor the names of its\n",
      "  contributors may be used to endorse or promote products derived from\n",
      "  this software without specific prior written permission.\n",
      "\n",
      "THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\n",
      "AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n",
      "IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\n",
      "DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\n",
      "FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n",
      "DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\n",
      "SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\n",
      "CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\n",
      "OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n",
      "OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n",
      "Location: /opt/anaconda3/envs/cogs18/lib/python3.11/site-packages\n",
      "Requires: numpy, python-dateutil, pytz, tzdata\n",
      "Required-by: seaborn\n"
     ]
    }
   ],
   "source": [
    "# see version information\n",
    "!pip show pandas"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.11.8"
  },
  "rise": {
   "scroll": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}