Starting to add code schematic content

Author: bjmorgan

CH40208/code_schematics/code_schematics.ipynb

@@ -0,0 +1,69 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "5d45e2b5-ee5e-4073-b724-6bf366dcc365",
+   "metadata": {},
+   "source": [
+    "# Planning Your Code and Writing A Code Schematic\n",
+    "\n",
+    "Just as it is a good idea to plan an essay or report before you start writing, it is a good idea to plan your code before you sit down and start typing.\n",
+    "\n",
+    "In the case of an essay, planning allows you to separate thinking about *what* you want to say from *how* you are going to tell it.\n",
+    "By creating a formal outline, you can identify exactly what points you want to make and how these will be organised to best communicate your overall idea to the reader.\n",
+    "Once you have your outline, you can then start piecing together the words, sentences, and paragraphs that will make up your full first draft.\n",
+    "While writing this first draft, you might realise that a particular part of your outline does not work as well as you had thought — you can modify your outline according to your new (hopefully better) idea and then return to your writing.\n",
+    "\n",
+    "As is the case for any moderately complex project, writing code benefits from planning. While it can be tempting to immediately start writing bits of code as you think through a problem, this can result in frustration and lost time as you get stuck in dead ends, or solve what you *thought* the problem was, rather than the real problem, or, halfway through, you realise that you do not actually know how to implement a critical step.\n",
+    "\n",
+    "In addition to saving you time and tears, planning your code will also help you to get better at programming. Writing a detailed code plan requires thinking through a complex problem and identifying how to deconstruct it into a sequence of well-defined, smaller, simpler problems that you know how to solve. This skill allows programmers to work on highly complex problems, as they are able to break them apart into small sub-problems that can be solved and then recombined.\n",
+    "\n",
+    "Like planning for any project, there are lots of possible ways to approach planning your code. In this course, we will cover an approach we call a “code schematic” — this is a document that is analogous to a detailed outline of an essay. Once written, a good detailed outline could be given to a second writer, and, providing they are reasonably competent, they could then produce an essay that makes the intended argument, even if the phrasing and writing style might be different. Similarly, a code schematic could be considered “good” if it could be given to a second programmer, who could then produce a code implementation that solves the original problem.\n",
+    "\n",
+    "A code schematic breaks a coding problem into a sequence of smaller steps and defines how these should be combined or linked. Because computers cannot think for themselves, a clear code schematic should include enough detail and specificity that there is no ambiguity about what each step of the code should do or how it should be done.\n",
+    "\n",
+    "We can illustrate this idea with the example of a relatively simple non-computational task — making tea.\n",
+    "\n",
+    "Here is a simple “code schematic” that attempts to solve this problem:\n",
+    "\n",
+    "1. Put the tea bags in the mugs\n",
+    "2. Boil the kettle\n",
+    "3. Pour the water into the mugs\n",
+    "4. Let the tea brew\n",
+    "5. Take the tea bags out\n",
+    "6. Serve the tea.\n",
+    "\n",
+    "We could also present this as a flow-chart:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1b635573-9b6a-443b-833f-b2d3ed5ad057",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "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.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}