006_Python_Statement_Indentation_Comments.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<small><small><i>\n",
    "All the IPython Notebooks in **Python Introduction** lecture series by **[Dr. Milaan Parmar](https://www.linkedin.com/in/milaanparmar/)** are available @ **[GitHub](https://github.com/milaan9/01_Python_Introduction)**\n",
    "</i></small></small>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python Statement, Indentation and Comments\n",
    "\n",
    "In this class, you will learn about Python statements, why indentation is important and use of comments in programming."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Python Statement\n",
    "\n",
    "Instructions that a Python interpreter can execute are called statements. For example, **`a = 1`** is an assignment statement. **`if`** statement, **`for`** statement, **`while`** statement, etc. are other kinds of statements which will be discussed later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multi-line statement\n",
    "\n",
    "In Python, the end of a statement is marked by a newline character. But we can make a statement extend over multiple lines with the line continuation character **`\\`**.\n",
    "\n",
    "* Statements finish at the end of the line:\n",
    "  * Except when there is an open bracket or paranthesis:\n",
    "  \n",
    "```python\n",
    ">>> 1+2\n",
    ">>> +3  #illegal continuation of the sum\n",
    "```\n",
    "  * A single backslash at the end of the line can also be used to indicate that a statement is still incomplete  \n",
    "  \n",
    "```python\n",
    ">>> 1 + \\\n",
    ">>>    2 + 3 # this is also okay\n",
    "```\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:39.565686Z",
     "start_time": "2021-10-02T06:13:39.533459Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "1+2    # assignment line 1\n",
    "+3     # assignment line 2\n",
    "\n",
    "# Python is only calculating assignment line 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "1+2 \\       # '\\' means assignment line is continue to next line\n",
    "+3\n",
    "```\n",
    "\n",
    ">**Note:** This would result in error because there should be no comment **`#`** or space after **`\\`**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:39.671639Z",
     "start_time": "2021-10-02T06:13:39.567639Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Method 1:\n",
    "\n",
    "1+2 \\\n",
    "+3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:39.777600Z",
     "start_time": "2021-10-02T06:13:39.676525Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "45"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "1 + 2 + 3 + \\\n",
    "4 + 5 + 6 + \\\n",
    "7 + 8 + 9"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is an explicit line continuation. In Python, line continuation is implied inside:\n",
    "1. parentheses **`( )`**, \n",
    "    For Example:\n",
    "    ```python\n",
    "(1+2\n",
    "             + 3) # perfectly OK even with spaces\n",
    "```\n",
    "2. brackets **`[ ]`**, and \n",
    "3. braces **`{ }`**. \n",
    "For instance, we can implement the above multi-line statement as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:39.929944Z",
     "start_time": "2021-10-02T06:13:39.781506Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Method 2:\n",
    "\n",
    "(1+2\n",
    "+3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.041275Z",
     "start_time": "2021-10-02T06:13:39.933850Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "45"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(1 + 2 + 3 +\n",
    "4 + 5 + 6 +\n",
    "7 + 8 + 9)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the surrounding parentheses **`( )`** do the line continuation implicitly. Same is the case with **`[ ]`** and **`{ }`**. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.160414Z",
     "start_time": "2021-10-02T06:13:40.047132Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['red', 'blue', 'green', '99']"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "['red',\n",
    "'blue',\n",
    "    'green', '99']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Python Indentation\n",
    "\n",
    "No spaces or tab characters allowed at the start of a statement: Indentation plays a special role in Python (see the section on control statements). For now simply ensure that all statements start at the beginning of the line.\n",
    "\n",
    "<div>\n",
    "<img src=\"img/ind1.png\" width=\"700\"/>\n",
    "</div>\n",
    "\n",
    "Most of the programming languages like C, C++, and Java use braces **`{ }`** to define a block of code. Python, however, uses indentation.\n",
    "\n",
    "A comparison of C & Python will help you understand it better.\n",
    "\n",
    "<div>\n",
    "<img src=\"img/ind2.png\" width=\"700\"/>\n",
    "</div>\n",
    "\n",
    "A code block (body of a **[function](https://github.com/milaan9/04_Python_Functions/blob/main/001_Python_Functions.ipynb)**, **[loop](https://github.com/milaan9/03_Python_Flow_Control/blob/main/005_Python_for_Loop.ipynb)**, etc.) starts with indentation and ends with the first unindented line. The amount of indentation is up to you, but it must be consistent throughout that block.\n",
    "\n",
    "Generally, four whitespaces are used for indentation and are preferred over tabs. Here is an example.\n",
    "\n",
    "> **In the case of Python, indentation is not for styling purpose. It is rather a requirement for your code to get compiled and executed. Thus it is mandatory!!!**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.314708Z",
     "start_time": "2021-10-02T06:13:40.167249Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "2\n",
      "3\n",
      "4\n",
      "5\n",
      "6\n"
     ]
    }
   ],
   "source": [
    "for i in range(1,11):\n",
    "    print(i)   #press \"Tab\" one time for 1 indentation\n",
    "    if i == 6:\n",
    "        break "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The enforcement of indentation in Python makes the code look neat and clean. This results in Python programs that look similar and consistent.\n",
    "\n",
    "Indentation can be ignored in line continuation, but it's always a good idea to indent. It makes the code more readable. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.437265Z",
     "start_time": "2021-10-02T06:13:40.325457Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n"
     ]
    }
   ],
   "source": [
    "if True:\n",
    "    print('Hello')\n",
    "    a = 6"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.559823Z",
     "start_time": "2021-10-02T06:13:40.447031Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n"
     ]
    }
   ],
   "source": [
    "if True: print('Hello'); a = 6"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "both are valid and do the same thing, but the former style is clearer.\n",
    "\n",
    "Incorrect indentation will result in **`IndentationError`**\n",
    "."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Python Comments\n",
    "\n",
    "Comments are very important while writing a program. They describe what is going on inside a program, so that a person looking at the source code does not have a hard time figuring it out.\n",
    "\n",
    "You might forget the key details of the program you just wrote in a month's time. So taking the time to explain these concepts in the form of comments is always fruitful.\n",
    "\n",
    "In Python, we use the hash **`#`** symbol to start writing a comment.\n",
    "\n",
    "It extends up to the newline character. Comments are for programmers to better understand a program. Python Interpreter ignores comments.\n",
    "\n",
    "Generally, comments will look something like this:\n",
    "\n",
    "```python\n",
    "#This is a Comment\n",
    "```\n",
    "\n",
    "Because comments do not **execute**, when you run a program you will not see any indication of the comment there. Comments are in the source code for **humans** to **read**, not for **computers to execute**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.682382Z",
     "start_time": "2021-10-02T06:13:40.563733Z"
    }
   },
   "outputs": [],
   "source": [
    "#This is a Comment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Single lined comment:\n",
    "In case user wants to specify a single line comment, then comment must start with **`#`**.\n",
    "\n",
    "```python\n",
    "#This is single line comment.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.804942Z",
     "start_time": "2021-10-02T06:13:40.685314Z"
    }
   },
   "outputs": [],
   "source": [
    "#This is single line comment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Inline comments\n",
    "If a comment is placed on the same line as a statement, it is called an inline comment. Similar to the block comment, an inline comment begins with a single hash (#) sign and followed by a space and comment.\n",
    "\n",
    "It is recommended that an inline comment should separate from the statement at least **two spaces**. The following example demonstrates an inline comment\n",
    "\n",
    "```python\n",
    ">>>n+=1  # increase/add n by 1\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:40.929942Z",
     "start_time": "2021-10-02T06:13:40.809827Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n=9\n",
    "n+=1  # increase/add n by 1\n",
    "n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Multi lined comment:\n",
    "\n",
    "We can have comments that extend up to multiple lines. One way is to use the hash **`#`** symbol at the beginning of each line. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.082284Z",
     "start_time": "2021-10-02T06:13:40.933849Z"
    }
   },
   "outputs": [],
   "source": [
    "#This is a long comment\n",
    "#and it extends\n",
    "#to multiple lines"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.236581Z",
     "start_time": "2021-10-02T06:13:41.086192Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello\n"
     ]
    }
   ],
   "source": [
    "#This is a comment\n",
    "#print out Hello\n",
    "print('Hello')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another way of doing this is to use triple quotes, either `'''` or `\"\"\"`.\n",
    "\n",
    "These triple quotes are generally used for multi-line strings. But they can be used as a multi-line comment as well. Unless they are not docstrings, they do not generate any extra code.\n",
    "\n",
    "```python\n",
    "#single line comment\n",
    ">>>print (\"Hello Python\"\n",
    "   '''This is\n",
    "   multiline comment''')\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.375251Z",
     "start_time": "2021-10-02T06:13:41.247325Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'This is also a\\nperfect example of\\nmulti-line comments'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "\"\"\"This is also a\n",
    "perfect example of\n",
    "multi-line comments\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.482679Z",
     "start_time": "2021-10-02T06:13:41.379163Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'This is also a\\nperfect example of\\nmulti-line comments'"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "'''This is also a\n",
    "perfect example of\n",
    "multi-line comments'''"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.620369Z",
     "start_time": "2021-10-02T06:13:41.488536Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello PythonThis is\n",
      "multiline comment\n"
     ]
    }
   ],
   "source": [
    "#single line comment\n",
    "print (\"Hello Python\"\n",
    "'''This is\n",
    "multiline comment''')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Docstrings in Python\n",
    "\n",
    "A docstring is short for documentation string.\n",
    "\n",
    "**[Python Docstrings](https://github.com/milaan9/04_Python_Functions/blob/main/Python_Docstrings.ipynb)** (documentation strings) are the **[string](https://github.com/milaan9/02_Python_Datatypes/blob/main/002_Python_String.ipynb)** literals that appear right after the definition of a function, method, class, or module.\n",
    "\n",
    "Triple quotes are used while writing docstrings. For example:\n",
    "\n",
    "```python\n",
    ">>>def double(num):\n",
    ">>>    \"\"\"Function to double the value\"\"\"\n",
    ">>>    return 3*num\n",
    "```\n",
    "\n",
    "Docstrings appear right after the definition of a function, class, or a module. This separates docstrings from multiline comments using triple quotes.\n",
    "\n",
    "The docstrings are associated with the object as their **`__doc__`** attribute.\n",
    "\n",
    "So, we can access the docstrings of the above function with the following lines of code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.729260Z",
     "start_time": "2021-10-02T06:13:41.626231Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Function to double the value\n"
     ]
    }
   ],
   "source": [
    "def double(num):\n",
    "    \"\"\"Function to double the value\"\"\"\n",
    "    return 3*num\n",
    "print(double.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To learn more about docstrings in Python, visit **[Python Docstrings](https://github.com/milaan9/04_Python_Functions/blob/main/Python_Docstrings.ipynb)** ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Help topics\n",
    "\n",
    "Python has extensive help built in. You can execute **`help()`** for an overview or **`help(x)`** for any library, object or type **`x`**. Try using **`help(\"topics\")`** to get a list of help pages built into the help system.\n",
    "\n",
    "`help(\"topics\")`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-10-02T06:13:41.882578Z",
     "start_time": "2021-10-02T06:13:41.733166Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Here is a list of available topics.  Enter any topic name to get more help.\n",
      "\n",
      "ASSERTION           DELETION            LOOPING             SHIFTING\n",
      "ASSIGNMENT          DICTIONARIES        MAPPINGMETHODS      SLICINGS\n",
      "ATTRIBUTEMETHODS    DICTIONARYLITERALS  MAPPINGS            SPECIALATTRIBUTES\n",
      "ATTRIBUTES          DYNAMICFEATURES     METHODS             SPECIALIDENTIFIERS\n",
      "AUGMENTEDASSIGNMENT ELLIPSIS            MODULES             SPECIALMETHODS\n",
      "BASICMETHODS        EXCEPTIONS          NAMESPACES          STRINGMETHODS\n",
      "BINARY              EXECUTION           NONE                STRINGS\n",
      "BITWISE             EXPRESSIONS         NUMBERMETHODS       SUBSCRIPTS\n",
      "BOOLEAN             FLOAT               NUMBERS             TRACEBACKS\n",
      "CALLABLEMETHODS     FORMATTING          OBJECTS             TRUTHVALUE\n",
      "CALLS               FRAMEOBJECTS        OPERATORS           TUPLELITERALS\n",
      "CLASSES             FRAMES              PACKAGES            TUPLES\n",
      "CODEOBJECTS         FUNCTIONS           POWER               TYPEOBJECTS\n",
      "COMPARISON          IDENTIFIERS         PRECEDENCE          TYPES\n",
      "COMPLEX             IMPORTING           PRIVATENAMES        UNARY\n",
      "CONDITIONAL         INTEGER             RETURNING           UNICODE\n",
      "CONTEXTMANAGERS     LISTLITERALS        SCOPING             \n",
      "CONVERSIONS         LISTS               SEQUENCEMETHODS     \n",
      "DEBUGGING           LITERALS            SEQUENCES           \n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(\"topics\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.10.9"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}