updating good coding practices notebook

Author: VuokkoH

notebooks/L3/gcp-3-pep8.ipynb

@@ -65,6 +65,11 @@
     "\n",
     "PEP 8 goes far beyond the scope of what we have learned so far during this course, and we recommend that you re-visit the guidelines every now and then when learning new things. **Here, we summarize some highlights that you can start applying to your code right away!**\n",
     "\n",
+    "- [Maximum line length](#Maximum-line-length)\n",
+    "- [Indentation](#Indentation)\n",
+    "- [Whitespace and binary operators](#Whitespace-and-binary-operators)\n",
+    "- [Avoid extraneous whitespace](#Avoid-extraneous-whitespace)\n",
+    "- [Write one statement per line](#Write-one-statement-per-line)\n",
     "\n"
    ]
   },
@@ -189,9 +194,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In addition, indentation is needed when breaking one command into multiple lines, such as in our example with the list `us_cities` above. \n",
+    "In our case, the first option with the conditional expression on one line is ok, as it is not that long afterall.\n",
     "\n",
-    "Following PEP 8 indentation guidelines, we can define `us_cities` also using a [hanging indent](https://www.python.org/dev/peps/pep-0008/#fn-hi). Note that there is no value on the first line of the list, and the closing bracket is lined up with the last line of the list:"
+    "In addition, indentation is needed when breaking one command into multiple lines, such as in our example with the list `us_cities` above, where we used the implied line continuation inside the brackets. Following PEP 8 indentation guidelines, we can define `us_cities` also using a [hanging indent](https://www.python.org/dev/peps/pep-0008/#fn-hi). Note that there is no value on the first line of the list, and the closing bracket is lined up with the last line of the list:"
    ]
   },
   {
@@ -238,7 +243,6 @@
    "cell_type": "code",
    "execution_count": 6,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -274,7 +278,6 @@
    "cell_type": "code",
    "execution_count": 8,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -299,7 +302,6 @@
    "cell_type": "code",
    "execution_count": 9,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -322,7 +324,6 @@
    "cell_type": "code",
    "execution_count": 10,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -345,17 +346,16 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### One thing per line    \n",
+    "### Write one statement per line    \n",
     "\n",
-    "Avoid compound statements (writing multiple statements on the same line).\n",
+    "Avoid writing multiple statements on the same line:\n",
     "https://www.python.org/dev/peps/pep-0008/#other-recommendations"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 11,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -380,7 +380,6 @@
    "cell_type": "code",
    "execution_count": 12,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -416,7 +415,6 @@
    "cell_type": "code",
    "execution_count": 14,
    "metadata": {
-    "collapsed": false,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -436,33 +434,43 @@
     "\n",
     "**Advanced Note**\n",
     "\n",
-    "You often have to **balance between code readability and code length**. While the rule of thumb is to write one statement per line, Python also has a set of compound statements which are able to squeeze multiple operations into one line. **List comprehensions** are a useful approach for creating lists in a consise way. We are not covering list comprehensions during the lessons, but here is a short example from the [Python documentation](https://docs.python.org/3/tutorial/datastructures.html):\n",
+    "You often have to **balance between code readability and code length**. PEP 8 guides us to generally avoid [compound statements](https://docs.python.org/3/reference/compound_stmts.html#compound-statements) (writing multiple statements on the same line). However, according to PEP 8, it might be sometimes ok to squeeze a short piece of code into one line, for example, with the`for` -statement. Sometimes you just have to judge yourself which option makes the code more readable and go for that.\n",
     "\n",
-    "This for loop iterates over a range, squares all values and appends them to a list: \n",
+    "One puzzling example regarding this guideline is the use of list comprehensions when defining lists. [List comprehensions](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are a useful approach for creating lists in a consise way. We are not covering list comprehensions during the lessons, but here is a short example from the [Python documentation](https://docs.python.org/3/tutorial/datastructures.html). Let's have a look at two options that produce the same output:\n",
+    "\n",
+    "*Option A) This for loop iterates over a range, squares all values and appends them to a list:*\n",
     "\n",
     "```\n",
     "squares = []\n",
     "for x in range(10):\n",
     "    squares.append(x**2)\n",
     "```\n",
-    "We can achieve the same output using a list comprehension:\n",
+    "*Option B) Square all values in the range using a list comprehension:*\n",
     "\n",
     "```\n",
     "squares = [x**2 for x in range(10)]\n",
     "```\n",
     "\n",
+    "**Both approaches are fine, and you can choose the option that you think makes the code more readable.**\n",
     "\n",
-    "In some cases, list comprehensions might make your code more readable and consise. In other cases, you might end up writing an excessively long statement which is difficult to read. In cases when PEP 8 (or your team) doesn't have a clear say on how to write the code, you can choose the option that you think makes the code more readable.\n",
+    "In some cases, list comprehensions might make your code more readable and consise. In other cases, you might end up writing an excessively long statement which is difficult to read. \n",
     "</div>\n"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "anaconda-cloud": {},
   "kernelspec": {
-   "display_name": "Python [conda env:Anaconda3]",
+   "display_name": "Python 3",
    "language": "python",
-   "name": "conda-env-Anaconda3-py"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -474,7 +482,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.6"
+   "version": "3.7.4"
   }
  },
  "nbformat": 4,