notebook-14-style-and-summary.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Wrapping Up (A Matter of Style)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Lesson Content \n",
    "\n",
    "- Style\n",
    "    - Why style matters\n",
    "    - Python style\n",
    "- Why???\n",
    "    - Why did I enter this world of pain?\n",
    "    - Where am I going?\n",
    "\n",
    "Welcome to _last_, Code Camp notebook! In this lesson we'll cover a number of things that don't fit anywhere else but which are essential to getting you on your way as a beginner programmer in Geocomputation and Spatial Data Science.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Style\n",
    "\n",
    "As with any other type of creative writing -- make no mistake, writing code is a creative activity! -- different people have different styles of writing. Extending the language metaphor, different programming languages have different styles as well and you can often tell what programming language someone learned first (or best) by the way they write their code in _any_ programming language. While it's _nice_ to work in the style that is considered 'best' in each language, what is more important is that you are consistent in how you write: that way, another person reading your code can get used to the way that you write and make better sense of what you're trying to do.\n",
    "\n",
    "### Variable Names\n",
    "\n",
    "So here are some common styles for variable names:\n",
    "\n",
    "| Variable Name | Language | Rationale |\n",
    "|:--------------|:---------|:----------|\n",
    "| my_variable | Python, Perl | Underscores (\"\\_\") make it easy to read 'words' in a variable name |\n",
    "| MyVariable | Java | Mixed Caps makes for shorter variable names that are easier to type |\n",
    "| my.variable | R | R allows full-stops in variable names, no other language does |\n",
    "\n",
    "### Comments\n",
    "\n",
    "Commenting code that they've written is something that programmers normally hate doing, because it's not _doing_ work after all... until you have to try to understand what you've done and why two days or two months later. You'd be surprised how quickly your memory of _why_ you did something one way, and not another, will fade and, with it, the risks that you were trying to avoid. It doesn't matter how clear your variable names are (_e.g._ `url_to_get` or `do_not_do_this`) you will eventually forget what is going on. Comments help you to avoid this, and they also allow you to write more concise, efficient code because your variable and function names don't have to do all the heavy lifting of explanation as well!\n",
    "\n",
    "How to comment well:\n",
    "\n",
    "- There are as many ways of commenting well as there are ways of writing code well -- the point is to be clear and consistent.\n",
    "- You might think of adding a _short_ comment on the end of a line of code if that line is doing something complex and not immediately obvious:\n",
    "```python\n",
    "import random\n",
    "random.seed(123456789) # For reproducibility\n",
    "```\n",
    "- You might think of adding a one-line or multi-line comment at the start of a _block_ of code that is achieving something specific:\n",
    "```python\n",
    "# Create a new data frame to \n",
    "# hold the percentage values\n",
    "# and initialise it with only\n",
    "# the 'mnemonic' (i.e. GeoCode)\n",
    "d_pct = pd.concat(\n",
    "    [d[t]['mnemonic']], \n",
    "    axis=1, \n",
    "    keys=['mnemonic'])\n",
    "```\n",
    "- You might think of using some formatting for a long _section_ of code that forms a key stage of your analysis:\n",
    "```python\n",
    "##############################\n",
    "# This next section deals with\n",
    "# extracting data from the \n",
    "# London Data Store and tidying\n",
    "# up the values so that they work\n",
    "# with pandas.\n",
    "##############################\n",
    "```\n",
    "- Finally, you can also use multi-line strings as a kind of comment format:\n",
    "```python\n",
    "\"\"\"\n",
    "=========================================================\n",
    "Extract pd2-level data from the price paid medians data\n",
    "=========================================================\n",
    "\"\"\"\n",
    "```\n",
    "\n",
    "Many programmers will mix all of these different styles together, but they will do so in a consistent way: the more complex the formatting and layout of the comment, the larger the block of code to which the comment applies.\n",
    "\n",
    "### Why Style Matters\n",
    "\n",
    "As we said at the start, style matters because it makes your code _intelligible_ to you, and to others. For professional programmers that is incredibly important because almost no one works on their own any more: applications are too complex for one programmer to get very far. So programmers need others to be able to read and interpret the code that they've written. As well, you might be asked to (or want to) go back to make changes to some code that you wrote some time ago -- if you've not commented your code or used a consistent style you're much more likely to break things. You might have heard of the Facebook motto \"Move fast and break things\" -- that doesn't refer to Facebook's web application, it refers to _paradigms_. \n",
    "\n",
    "![Jobs I've Been Fired From](https://imgs.xkcd.com/comics/move_fast_and_break_things.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why???\n",
    "\n",
    "We'd like to wrap up Code Camp by revisiting the question of 'why' -- why invest a lot of time and energy in learning to code? There are a host of reasons, but we'd like to pick out a few of the ones that we think are most important for undergraduate students:\n",
    "\n",
    "1. Coding teaches logical thinking: right from the start, coding reinforces logical thinking. A computer will try to do _exactly_ what you say, regardless of how inappropriate or illogical that statement might be. To become a better programmer you will need to develop a good idea of what you're trying to achieve, the steps involved in getting there, and you'll need an eye for detail as well since `my_variable` is not the same as `myvariable`.\n",
    "\n",
    "2. Coding teaching abstraction: this might seem a bit of a strange point coming right after the one about an 'eye for detail', but it's true! Writing code is not just about solving for one row of data, or 1,000, it's about solving the problem in a _general_ way: mapping and analysis tools like [PySAL](http://pysal.readthedocs.io/en/latest/) or [Folium](https://github.com/python-visualization/folium) weren't create to solve one mapping or spatial analysis problem, but a _range_ of them! Well-written code is easy to adapt and re-use (and in follow-on classes we'll look at how to encapsulate useful snippets of code in functions so that it's even easier) because you aren't just thinking about \"I have to process population data for 20 English cities\" but about \"How do I manage population data in many different formats about cities anywhere in the world?\". You also need to have, in your head, a high-level _model_ of how the computer is processing the data so that you can frame your solution appropriately. Again, that's abstraction.\n",
    "\n",
    "3. Coding is scalable: there's a lot of 'start-up cost' involved with a coding solution, but once you get over this hump it's highly scalable. One of us has been working on a Machine Learning problem to try to predict gentrification in London from 2011-2021 using the period from 2001-2011. This involves not only downloading more than 30 data sets from the [ONS/NOMIS](https://www.nomisweb.co.uk/) and the [London Data Store](https://data.london.gov.uk/) in order to build a model using 168 variables, it also involves making difficult choices about how to handle highly skewed data which makes accurate prediction much more difficult. Using Python, we can try _each_ of the options available and see which one work best, even though this involves reprocessing 168 variables, re-mapping 15 maps, and re-outputting 3 data files for use in QGIS. \n",
    "\n",
    "4. Coding is replicable: the 'crisis of replicability' has enormous implications for medicine, psychology, policy, planning, and environmental science. Without the ability to check how data was collected, processed, and analysed we are basically 'flying blind'. You might have heard about the [Excel error used to justify austerity](http://theconversation.com/economists-an-excel-error-and-the-misguided-push-for-austerity-13584) or about the [crisis in replicability](http://www.newyorker.com/tech/elements/the-crisis-in-social-psychology-that-isnt)? Or that only [positive trials](https://www.scientificamerican.com/article/trial-sans-error-how-pharma-funded-research-cherry-picks-positive-results/) of a drug are published? These are parts of a larger debate within the sciences about how much of the scientific process should be conducted 'in the open' -- is it just data? or is it code as well? Increasingly, journals and scientists are arguing for it to be both.\n",
    "\n",
    "5. Coding is empowering: if you stick with it you'll probably find that, one afternoon, you start coding around 3pm and suddenly realise that it's dark out, you're hungry, and you've been coding non-stop all the way to 9pm! We don't recommend this as everyday practice, but it's a sign of how engaging coding can be, how easy it is to enter '[flow](https://en.wikipedia.org/wiki/Flow_(psychology))', and how exciting it can be to solve real problems and achieve a real output. Ultimately, we think that 'bending' a computer to your will -- and, as importantly, figuring out how to frame a human problem in logical terms that a computer can handle -- is a tremendously empowering experience: that day you click 'run' or hit 'enter' and the computer chews away at a data set for 10 seconds or 10 hours **and** comes back to you with a solution to your problem is profoundly thrilling because it means that you've done work that _works_ on multiple levels simultaneously (it works at the fine-scale of syntax _and_ at the conceptual level of design).\n",
    "\n",
    "We hope you'll get there and we hope you'll stick it out until you do! If you invest the time and effort then we're pretty confident that _any_ of you can become a competent programmer: but don't take our word for it, ask some of this year's Third Years what they think! And here is some more food for thought:\n",
    "\n",
    "1. The National Academy's [Understanding the Changing Planet: Strategic Directions for the Geographical Sciences](https://www.nap.edu/read/12860/chapter/18#118)\n",
    "2. The RGS's [Data Skills in Geography](http://www.rgs.org/OurWork/Schools/Data+skills+in+geography/Data+skills+in+geography.htm) (especially [Quantitative Skills in Geography](http://www.rgs.org/OurWork/Research+and+Higher+Education/Learning+teaching+and+research+in+higher+education/Quantitative+Teaching+and+Learning+in+Geography/Quantitative+Methods+in+Geography.htm)).\n",
    "\n",
    "\n",
    "**Good luck!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Credits!\n",
    "\n",
    "#### Contributors:\n",
    "The following individuals have contributed to these teaching materials: \n",
    "- [James Millington](https://github.com/jamesdamillington)\n",
    "- [Jon Reades](https://github.com/jreades)\n",
    "\n",
    "#### License\n",
    "The content and structure of this teaching project itself is licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license](https://creativecommons.org/licenses/by-nc-sa/4.0/), and the contributing source code is licensed under [The MIT License](https://opensource.org/licenses/mit-license.php).\n",
    "\n",
    "#### Acknowledgements:\n",
    "Supported by the [Royal Geographical Society](https://www.rgs.org/HomePage.htm) (with the Institute of British Geographers) with a Ray Y Gildea Jr Award.\n",
    "\n",
    "#### Potential Dependencies:\n",
    "This notebook may depend on the following libraries: None"
   ]
  }
 ],
 "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}