3 - Python 10min a day - Commenting - what Python ignores is useful for you!.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"assets/jeremy-lapak-CVvFVQ_-oUg-unsplash.png\" alt=\"Python Envs\" style=\"display: block; margin: 0 auto\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Learning Python 10 minutes a day #3\n",
    "## Commenting: what Python ignores is useful for you!\n",
    "[Medium article link](https://towardsdatascience.com/learning-python-10-minutes-a-day-3-af2967c34a36)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a [series](https://python-10-minutes-a-day.rocks) of short 10 minute Python articles helping you to get started with Python. I try to post an article each day (no promises), starting from the very basics, going up to more complex idioms. Feel free to contact me on [LinkedIn](https://www.linkedin.com/in/dennisbakhuis/) for questions or requests on particular subjects of Python, you want to know about."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Everyone knows that commenting is important and with each project you probably say to yourself: ‘In the next project I will pay more attention to commenting’. With a Notebook you already have a great structure, but it is still useful to have regular comments. Sometimes, a comment can help explain a certain assumption or why a setting was chosen. Or to simply have an inline explanation of a parameter. Also, when adding special comments such as docstrings from the start, if you ever need to convert a Notebook to a regular Python script (which is dead simple), you immediately have the explanation embedded."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Comments in Python start with a “#”. When Python sees the hashtag, it ignores everything that is behind that part. Also when debugging or trying different ways to code an algorithm, it is useful to comment out code. In many editors, including Jupyter you can comment/uncomment a line using “ctrl-/”. This works with the current line, or multiple lines that are selected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Hey ! I am a comment\n",
    "this_part = \"is a not comment\"  # this part is comment\n",
    "\n",
    "# this_part = \"is commented out\"  # and therefore will also be ignored"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a formatting standard, it is advised to have two spaces between an inline comment and the actual comment as is done in the previous code snipped. Adding comments is great and try to be complete. One thing to avoid however, is to over-comment. Over-commenting means that you comment the obvious. This is especially true for Python, which is designed to be readable. For example make a comment that you will import packages, followed by the import keyword is clearly over-commenting and does not add information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import packages\n",
    "import time\n",
    "import os"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other languages like C or Java have the ability to create multi-line comments. Natively, Python does not have multi-line comments and the best way is simply use a hashtag at the start of each line. For a special occasion, you can create multi-line comments using triple quotation marks. This is actually not a comment but a multi-line string, which is not assigned to a label. If it is not assigned, it is ignored by the Python interpreter. Technically, you can put these unassigned strings everywhere in the code, but when putting them inside a Class or Function definition, these have the meaning of a DocString. A DocString is a short piece of special commenting to describe the function. While you are free to create your own format for a DocString, some large projects such as Pandas or Numpy have standardized these. Pandas has a nice [guide](https://pandas.pydata.org/pandas-docs/stable/development/contributing_docstring.html) on how to structure these. These are then used to automatically create documentation. We have not yet discussed creating functions, but I think the example will be quite clear:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add_values(value1, value2):\n",
    "    \"\"\"\n",
    "    Adding two values\n",
    "    \n",
    "    When two numerical values are provided this function\n",
    "    calculates the sum of the two values and returns the\n",
    "    result.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    value1 : float\n",
    "         The first value.\n",
    "    value2 : float\n",
    "          The second value.\n",
    "          \n",
    "    Returns\n",
    "    -------\n",
    "    float\n",
    "         The sum of value1 and value2\n",
    "    \"\"\"\n",
    "    return value1 + value2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are different ways to style these, but the key element is readability. Getting a function as described in the previous snippet is very clear. We might argue that the function name would already be clear enough and therefore, we did some over-commenting, but you will probably create more complex functions and your colleagues, and most probably also your future self, will thank you for making high quality comments and DocStrings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The reason why DocStrings are in general a good idea is that these can be accessed anywhere in IPython and related. If you are unsure what the parameters of a certain function are, or completely forgot what the function does, you can always acces the DocString using “?”. By typing the function and instead of writing the parenthesis, you add a question mark, you will get the DocString of that function. If you use a full-fledged IDE, these are sometimes shown when you hover over a function with your mouse, or when you are between the parenthesis. I find these things distracting and generally turn these off. If you like these things, Visual Studio Code sure is nice, and I also remember that Jupyter Lab has a plugin which can do that."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"assets/day3-docstring.png\" alt=\"Python Envs\"  width=\"600\" style=\"display: block; margin: 0 auto\" />\n",
    "\n",
    "*To get help for a function in Python, simply add a ? instead of the parenthesis.*\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Practice for today:\n",
    "1. In a new Notebook create some simple calculations.\n",
    "2. Add comments around your calculations and add inline comments\n",
    "3. Comment and uncomment lines using ctrl-/.\n",
    "4. Create a DocString for the following function:\n",
    "\n",
    "```Python\n",
    "def average_three_values(value1, value2, value3):\n",
    "    return (value1 + value2 + value3) / 3\n",
    "```\n",
    "\n",
    "5. Get help for your own function using the ‘?’\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have any questions, feel free to contact me through [LinkedIn](https://www.linkedin.com/in/dennisbakhuis/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}