prodigiouspython/Chapter_3/1_Comments_and_docstrings.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9d6e87b1-c034-4c61-854c-d21e2171cda5",
   "metadata": {},
   "source": [
    "# Comments and Docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b99df3e1-f6a3-4b5f-b66e-bf999a5f6d33",
   "metadata": {},
   "source": [
    "Comments are used to explain the code. The interpreter doesn't execute the comments. There are 3 types of comments in Python:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2c131ff-14a4-4c31-9bcf-4aacf8da48e9",
   "metadata": {},
   "source": [
    "* Single Line\n",
    "* In-Line\n",
    "* Multi Line"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80a185f7-64b1-4bcf-b90f-13bf0e16893e",
   "metadata": {},
   "source": [
    "## Single Line\n",
    "\n",
    "Single line comments are written in a single line. Single line comments start with `#`\n",
    "\n",
    "```Python\n",
    "# Here's a single line comment\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd73420a-d428-4983-a641-4bc471ac3ec7",
   "metadata": {},
   "source": [
    "## In-Line\n",
    "\n",
    "In-Line comments are written beside the code.\n",
    "\n",
    "```Python\n",
    "print(\"Hello\")  # Here's a In-Line comment\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54eba953-84f0-47ce-88ab-7bccaab31ba2",
   "metadata": {},
   "source": [
    "## Multi Line\n",
    "\n",
    "Sometimes we need to write a huge explanation using comments, in those cases we do use multi-line comments. multiline comments are enclosed in `\"\"\" \"\"\"` or `''' '''`\n",
    "\n",
    "\n",
    "```Python\n",
    "\"\"\"\n",
    "Here's a \n",
    "multiline comment.\n",
    "\"\"\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81c3a0f8-a840-49e2-bb5d-72b51c27daca",
   "metadata": {},
   "source": [
    "## Docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26de1d2f-827d-472c-88be-84c48d2f9f0a",
   "metadata": {},
   "source": [
    "Docstrings are specific type of comments that are stored as a attribute to the module, class, method or function.\n",
    "\n",
    "Docstrings are written similar to the multi-line comments using `\"\"\" \"\"\"` or `''' '''`, the only difference would be they are written exactly at the start(first statement) of the module, class, method or function."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "603b0355-d7d3-494a-b925-f4c52a443e68",
   "metadata": {},
   "source": [
    "Docstrings can be programmatically accessed using the `__doc__` method or through the built-in function `help`. Let's give a try 😎."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cff0a379-ff94-4c15-b7ba-bfc26a5dc0ef",
   "metadata": {},
   "outputs": [],
   "source": [
    "def double_the_value(value: int):\n",
    "    \"\"\"Doubles the integer value passed to the function and returns it.\"\"\"\n",
    "    return value * 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d863017-74a4-47ba-a4bd-251a8f9d90da",
   "metadata": {},
   "source": [
    "### Using help"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eca619f5-3150-480c-9574-f9a2d307c10b",
   "metadata": {},
   "source": [
    "`help` function provides the docstrings as well as the information about the module, class, method or function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b68d4d2-ac35-48ba-9a5f-40b3b324582c",
   "metadata": {},
   "outputs": [],
   "source": [
    "help(double_the_value)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6260c14b-4c3a-470c-839a-31090eb36e8a",
   "metadata": {},
   "source": [
    "### Using `__doc__`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "904e5b00-ab9d-4ae9-ae88-17c30b5b2ae5",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(double_the_value.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef73c12b-e5c4-4cd7-b764-1a2c52db8a0d",
   "metadata": {},
   "source": [
    "Can we use the single line comments instead of multi-line docstrings 🤔? Let's try this as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "832b9a67-aec0-4641-b5d8-5ed30acb0aa2",
   "metadata": {},
   "outputs": [],
   "source": [
    "def test_single_line_comment_as_docstring():\n",
    "    # This is a single-line comment\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9a0ff3b2-11e7-4628-8fa2-b6eb310d9a75",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(test_single_line_comment_as_docstring.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4235bf2a-168a-4a0f-9d05-4ca663ee1ffb",
   "metadata": {},
   "source": [
    "We can see that `None` is printed, which explains that we can't use single-line comments as docstrings 🙂"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "603f861a-bda5-4730-bca9-21222dc6d3b7",
   "metadata": {},
   "source": [
    "## Docstrings for documentation of code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0512378-cc5f-4f66-8279-914c7292a708",
   "metadata": {},
   "source": [
    "[PEP-257](https://www.python.org/dev/peps/pep-0257/) defines two types of docstrings. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "491feb4b-d434-4658-92bd-10e0cce64104",
   "metadata": {},
   "source": [
    "* One-Line docstring\n",
    "* Multi-Line docstring"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "068712db-f188-41da-97b9-2db8464bd9f9",
   "metadata": {},
   "source": [
    "### [One-Line docstring](https://www.python.org/dev/peps/pep-0257/#one-line-docstrings)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a91c0da-53a9-4269-a107-a3eae7d07cd6",
   "metadata": {},
   "source": [
    "One-line docstrings are suited for short and simple Modules, classes, methods or functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7427ffc7-892c-47b5-9d19-0e6308a72cb1",
   "metadata": {},
   "outputs": [],
   "source": [
    "def one_line_docstring():\n",
    "    \"\"\"This is a one-line docstring\"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19766973-2ba4-4263-a103-32248c851bfa",
   "metadata": {},
   "source": [
    "### [Multi-Line docstring](https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d5caed4-d332-4850-943a-ab2aabccaac2",
   "metadata": {},
   "source": [
    "Multi-line docstrings are suited for long, complex Modules, classes, methods or functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b3ff74c7-01ca-47b0-9d2c-5088918903b2",
   "metadata": {},
   "outputs": [],
   "source": [
    "def multi_line_docstring(arg1: int, arg2: str) -> None:\n",
    "    \"\"\"\n",
    "    This is a multi-line docstring.\n",
    "\n",
    "    Arguments:\n",
    "      arg1 (int): Argument 1 is an integer.\n",
    "      arg2 (str): Argument 2 is a string.\n",
    "    \"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f2a956a4-b82c-4f99-bb78-4074020e7f1e",
   "metadata": {},
   "source": [
    "## Styles of docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfdfc61b-86d1-4963-ab39-e9a22b939c0a",
   "metadata": {},
   "source": [
    "There are multiple styles of writing docstrings such as [reStructuredText](https://docutils.sourceforge.io/rst.html), [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings), [Numpy style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).\n",
    "\n",
    "We could use any of the above docstrings style as long as we stay consistent. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33e1e1a7-37f9-4c2e-aa84-ae1f5929d8ce",
   "metadata": {},
   "source": [
    "[Sphinx](https://www.sphinx-doc.org/en/master/) is a tool that generated beautiful HTML based documentation 📜 from the docstrings we provide in our code. reStructuredText is the default style, for other styles like Google Python style, numpy we could use plugins like [Napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html).\n",
    "\n",
    "Sphinx also provides various templates we can choose from to create the HTML documentation out of it. 😎♥️"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed5c9557-9016-47bf-8863-4c9e52b81341",
   "metadata": {},
   "source": [
    "### A meme on Documentation 😂"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83315695-883f-43ba-af7b-38890402b2be",
   "metadata": {},
   "source": [
    "![Documentation](https://prodigiouspython.github.io/AssetStore/Chapters_1-5/Chapter_3/resources/documentation.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f11b487-3e9f-489b-aad5-324e2c0c678d",
   "metadata": {},
   "source": [
    "It's always good and professional to have our code documented 🙂."
   ]
  }
 ],
 "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.9.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}