04_Documenting_Code.ipynb

{
 "metadata": {
  "celltoolbar": "Slideshow",
  "name": "",
  "signature": "sha256:4cc6e24e56cbdbcdfef73fc87d13578f4be576627819771f83a5c116b6bbc37c"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Best Practices - Documenting Code\n",
      "================================="
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Why bother?\n",
      "-----------\n",
      "\n",
      "+ If anyone besides you will ever use your code (this includes future you) do *eveyone* a favour and document it properly.\n",
      "+ Even if you are the only person using your code, document it because you never know when you will need it again.\n",
      "    + e.g. Last month I picked up a code I'd written 7 years ago and was able to modify it and reuse it."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "What to document\n",
      "----------------\n",
      "\n",
      "+ User documentation\n",
      "+ Developer documentation"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "User documentation\n",
      "------------------\n",
      "\n",
      "The purpose of user documentation is to enable someone else to use your code for what it was designed for. **Assume they are stupid.**\n",
      "\n",
      "+ Minimally needs to explain how to use the basic functions of the code.\n",
      "    + Can help to include an example.\n",
      "    + Put licensing, warranty and copyright information in.\n",
      "    + Version of the code that the docs apply to.\n",
      "+ Extra things you can include:\n",
      "    + How to install the code (and the prerequisites);\n",
      "    + A CHANGELOG with thing that may have affected the way they expect the code to work;\n",
      "    + Methodologies used in the code and their references;\n",
      "    + All availabe options and their effects;\n",
      "    + Advanced features for people who like to tinker;\n",
      "    + Reasoning behind the code;\n",
      "    + FAQs;\n",
      "    + What to do, or who to contact when it breaks."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "How to document\n",
      "---------------\n",
      "\n",
      "+ Use whatever means you think will be most effective for you to communicate your documentation.\n",
      "    - But also most effective to distribute too\n",
      "\n",
      "+ The documetation for Python and many other software projects is written in Sphinx [http://sphinx-doc.org/](http://sphinx-doc.org/).\n",
      "    - You can see many examples on [https://readthedocs.org/](https://readthedocs.org/). (check the sidebars for source code links)\n",
      "    - You can see my example at [http://titan.chem.uottawa.ca/CHM8309I/faps/html](http://titan.chem.uottawa.ca/CHM8309I/faps/html).\n",
      "    - Some guidelines that are used in Python [http://docs.python.org/devguide/documenting.html](http://docs.python.org/devguide/documenting.html).\n",
      "\n",
      "To get started quickly with sphinx you run the command `sphinx-quickstart` in a terminal and answer some questions about your project. Put your documentation (written in _reStructuredText_) in the folder then edit the file `index.rst` to include other files in your documentation, and provided you created the makefiles you can run `make html` to generate the documentation."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Be aware that likely nobody will ever read your documentation, and then only as a last resort. Find out how you can put help at the commandline (`argparse` helps you build a `--help` option) or include a GUI menu or link to the help.\n",
      "\n",
      "    % cliswitch.py --help\n",
      "    usage: cliswitch.py [-h] [-v] [-q] [-o CMDOPTS] [-j JOB_TYPE] [job_name]\n",
      "\n",
      "    Fapswitch function switching program\n",
      "\n",
      "    positional arguments:\n",
      "      job_name              Name for job\n",
      "\n",
      "    optional arguments:\n",
      "      -h, --help            show this help message and exit\n",
      "      -v, --verbose         Increase verbosity. Specify more times for more\n",
      "                            debugging information. Cancels '--quiet'.\n",
      "      -q, --quiet           Decrease verbosity. Specify more times for less\n",
      "                            output. Cancels '--verbose'.\n",
      "      -o CMDOPTS, --option CMDOPTS\n",
      "                            Set program options as section.key=value pairs. Use\n",
      "                            \"quotation marks\" if options contain spaces.\n",
      "      -j JOB_TYPE, --job-type JOB_TYPE\n",
      "                            Read preconfigured job settings from job-type.fap in\n",
      "                            the user ~/.faps/ directory\n",
      "                            "
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Code documentation\n",
      "------------------\n",
      "\n",
      "**Self documenting code** is one of the easiest ways to document code for yourself and others reading your code. *In an ideal world your code would be so well written that it would be perfectly readable and interpretable*. Compare:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def g(x, y):\n",
      "    return x * 1 + y * 100\n",
      "\n",
      "def price_with_tax(price, tax_rate_percent=13.0):\n",
      "    tax_to_add = price * (tax_rate_percent / 100)\n",
      "    return price + tax_to_add"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "+ The choice of descriptive names means that the code describes what it does without further elaboration. \n",
      "+ This is not always sufficient. \n",
      "    + Sometimes you will need to do something that might not be obvious from reading the code."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Comments\n",
      "--------\n",
      "\n",
      "+ Use **comments** to describe **why** the code does what it does.\n",
      "    + Explain reasoning that is not obvious from the code.\n",
      "    + In Python comments begin with the `#` symbol and continue to the end of the line. \n",
      "    + If you put them on the same line as code then make sure to have at least two spaces after the code."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def price_with_tax(price, tax_rate=13.0):\n",
      "    \"\"\"Return the price with percent tax rate included (defaults to ON HST)\"\"\"\n",
      "    # Convert from percent to fraction by multiplication instead of division as it is faster\n",
      "    tax_to_add = price * tax_rate * 0.01\n",
      "    return price + tax_to_add  # add on the tax because the government are greedy"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "+ String literals `\"\"\"...\"\"\"` are also comments here, but they have special meaning when used correctly.\n",
      "+ These so-called **docstrings** document whatever object they are attached.\n",
      "    + They are accessible by _introspecting_ the code. \n",
      "    + This makes it possible to do IntelliSense type popups in fancy editors.\n",
      "+ Note that the docstrings do not need to say \"This function\" or go in to huge detail about the arguments as these are already known or available through introspection.\n",
      "+ Say what is expected to be returned and the types of the arguments if they are unexpected."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import inspect\n",
      "\n",
      "inspect.getdoc(price_with_tax)"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 3,
       "text": [
        "'Return the price with percent tax rate included (defaults to ON HST)'"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "inspect.getargspec(price_with_tax)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 4,
       "text": [
        "ArgSpec(args=['price', 'tax_rate'], varargs=None, keywords=None, defaults=(13.0,))"
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "+ You can find much more information about docstrings where they have their own PEP.\n",
      "    + [http://www.python.org/dev/peps/pep-0257/](http://www.python.org/dev/peps/pep-0257/)\n",
      "+ Some projects require very in depth docstrings including examples and references. The NumPy and SciPy packages, for example:\n",
      "    + [https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)\n",
      "+ Docstrings have the benefit that it is possible to automatically generate some developer documentation from the source code.\n",
      "+ `epydoc` is one of many: [http://titan.chem.uottawa.ca/CHM8309I/fapswitch/html/](http://titan.chem.uottawa.ca/CHM8309I/fapswitch/html/)\n",
      "+ `sphinx-apidoc` can also integrate with your Sphinx documentation."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Other languages\n",
      "---------------\n",
      "\n",
      "+ Doxygen is probably the most common and works with many languages.\n",
      "    + Put specially formatted comments in the code.\n",
      "    + Generates API-docs for developers"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Even works with Fortran as long as you have used the appropriate commenting styles (customisable).\n",
      "\n",
      "    !-----------------------------------------------------------------------------\n",
      "    !> This routine calculates the correction necessary to go from the\n",
      "    !> distribution g (which includes the correction of the parallel\n",
      "    !> vector potential) to the distribution f\n",
      "    !-----------------------------------------------------------------------------\n",
      "    subroutine g2f_correct\n",
      "    ..\n",
      "    .."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "+ IntelliSense and tools included in Microsoft Visual Studio interact with special XML documentation\n",
      "    + Denerate documentation from it.\n",
      "    + Introspect inside the IDE\n",
      "\n",
      "Example:\n",
      "\n",
      "    interface TestInterface\n",
      "    {\n",
      "        /// <summary> \n",
      "        /// Documentation that describes the method goes here. \n",
      "        /// </summary> \n",
      "        /// <param name=\"n\">\n",
      "        /// Parameter n requires an integer argument. \n",
      "        /// </param> \n",
      "        /// <returns> \n",
      "        /// The method returns an integer. \n",
      "        /// </returns> \n",
      "        int InterfaceMethod(int n);\n",
      "    }\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Problems\n",
      "--------\n",
      "\n",
      "The most common problem with comments is that they can easily become out of date. Be diligent when maintaining your code to keep your comments in line with what is written!"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def price_with_tax(price, tax_rate=20.0):\n",
      "    \"\"\"Return the price with percent tax rate included (defaults to ON HST)\"\"\"\n",
      "    # Convert from percent to fraction by multiplication instead of division as it is faster\n",
      "    tax_to_add = superfast_c_tax_calculator(price, tax_rate)\n",
      "    return price + tax_to_add  # add on the tax because the government are greedy"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    }
   ],
   "metadata": {}
  }
 ]
}