01_literate_programming.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preface: Literate Data Analysis vs. Literate Programming\n",
    "\n",
    "Data analysis already has a lot of vocabulary surrounding artful presentation. It is well known that data on it's own isn't useful. Even after the data has been cleaned and transformed, it isn't any good sitting in a database. There is an important emphasis on visualization, and even storytelling, because the data simply doesn't have value otherwise.\n",
    "\n",
    "Software by itself doesn't neccessitate have such a culture. The end product of software is not well-communicated information. From the user perspective, it is simply a set of features with a binary state: they work or they don't. So it is extremely easy to confuse the inherent value of the project the state of each one of these features.\n",
    "\n",
    "As computer 'scientists' and software 'engineers' (both of these monikers which were self-termed) there is a lot of culture around developing terse, elegant, and succinct. There are places where this type of code are helpful, specifically when it significantly improves the importance of the program. But I believe this style of code should generally be eshewed. It isn't just anodyne, it actively prevents the program from being understood by future programmers. In contrast, literate programming, though not a cultural mainstay, provides many aspects of softwrae sustainability. On this page, we will address what makes a program literate. In the next, what makes literate programming, and by extension software sustainability, valuable.\n",
    "\n",
    "\n",
    "# Literate Programming\n",
    "\n",
    "Perhaps you've heard of literate programming, or perhaps not. If you are like I was, you might have an underdeveloped notion that literate programming has to do with good comments and documentation generation. The reality is much more ground breaking, and the story of literate programming begins with the story Donald Knuth, a computer scientist, mathematician, and professor emeritus at Stanford University. He is also the 1974 recipient of the ACM Turing Award, given to him for his groundbreaking work on the analysis of algorithms.\n",
    "\n",
    "His accomplishments are manifold, but I think it can be safely argued that Knuth isn't one of the most ubiquitous computer scientists of all time just because his academic work was excellent. His success comes from his empassioned development of effective communication techniques.\n",
    "\n",
    "Knuth is largely famous his series of volumes called *The Art of Computer Programming* which he started writing in the 60's. When he was writing the second volume, the typesetting he had used from the first volume became unavailable. So he worked on a little side project for about eight years called TeX (the predecesor of LaTeX). Perhaps you've heard of it. It might seem striking that a brilliant academic took so many years away from his life's work (he still isn't finished publishing the last volumes) just to marginally imporove the readability of his texts. But Knuth knows the value of proper organization and visualization to improve overall comprehension of his work to his very large audience.\n",
    "\n",
    "> With good typography you can perceive the structure, instead of imagining the text as just a chaotic string of characters. It’s much better when those characters are arranged on a page in some reasonable way. <cite data-cite=\"7555637/4YB5CPFB\"></cite>\n",
    "\n",
    "After this brief foray, Knuth continuted producing new volumes. In 1984, he used his expertise in technical communication to publish *Literate Programming*. This work introduced the idea of writting computing programs as readable works of literature.\n",
    "\n",
    "As we are using Jupyter Notebooks for development, the technical details presented in the book aren't relevant to us, but the fundamental principles remain the same.\n",
    "\n",
    ">  The computer programs that are truly beautiful, useful, and profitable must be readable by people. So we ought to address them to people, not to machines. <cite data-cite=\"7555637/58JGCE95\"></cite>\n",
    "\n",
    "Firstly, this argument can be direcly to programming languages, making Python a very attractive candidate. On top of this Jupyter seems like a good environment for this kind of development. Jupyter supports markdown and LaTeX, making supporting text easier to read and write than comments or documentation. Jupyter ships with easily created *and copied* visual components that allow developers to interact with individual parts of a complex user interface. Finally, Jupyter provides the ability to easily execute small pieces of code to demonstrate the results of small code chuncks along the way to a more complicated result. Leaving these stepping stones in the codebase perpetuates narrative-style documentation. One might even leave behind examples of design that didn't work in order to leave traces of the thought process behind certain design decisions. All of this extra information contributes to the sustainability of the software through time.\n",
    "\n",
    ">  All of the major problems associated with computer programming—issues of reliability, portability, learnability, maintainability, and efficiency are ameliorated when programs and their dialogs with users become more literate. <cite data-cite=\"7555637/58JGCE95\"></cite>\n",
    "\n",
    "\n",
    "Naturally, the next question is how to effectively use notebooks to promote literate programming in any of Jupyter's supported languages. These tutorials will address exactly that.\n",
    "\n",
    "### Bibliography\n",
    "\n",
    "<div class=\"cite2c-biblio\"></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "cite2c": {
   "citations": {
    "7555637/4YB5CPFB": {
     "abstract": "Donald E. Knuth is Professor Emeritus of The Art of Computer Programming at Stanford University. In this oral history, Knuth ranges over a number of subjects in software development including software patenting, alphametics, structural programming, and collaboration. The oral history includes material on the writing of The Art of Computer Programming as well as his early education and Lutheran heritage.",
     "author": [
      {
       "family": "Knuth",
       "given": "Donald E"
      }
     ],
     "id": "7555637/4YB5CPFB",
     "language": "en",
     "page": "27",
     "page-first": "27",
     "title": "Conducted by Philip L. Frana",
     "type": "article-journal"
    },
    "7555637/58JGCE95": {
     "DOI": "10.1093/comjnl/27.2.97",
     "URL": "https://academic.oup.com/comjnl/article-lookup/doi/10.1093/comjnl/27.2.97",
     "accessed": {
      "day": 3,
      "month": 12,
      "year": 2020
     },
     "author": [
      {
       "family": "Knuth",
       "given": "D. E."
      }
     ],
     "container-title": "The Computer Journal",
     "id": "7555637/58JGCE95",
     "issue": "2",
     "issued": {
      "month": 2,
      "year": 1984
     },
     "language": "en",
     "page": "97–111",
     "page-first": "97",
     "title": "Literate Programming",
     "type": "article-journal",
     "volume": "27"
    }
   }
  },
  "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.9.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}