coding_standards/Python_coding_standards.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import print_function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![NASA](http://www.nasa.gov/sites/all/themes/custom/nasatwo/images/nasa-logo.svg)\n",
    "\n",
    "<center>\n",
    "<h1><font size=\"+3\">GSFC Python Bootcamp</font></h1>\n",
    "</center>\n",
    "\n",
    "---\n",
    "\n",
    "<CENTER>\n",
    "<H1 style=\"color:red\">\n",
    "Python Coding Standards\n",
    "</H1>\n",
    "</CENTER>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=\"red\"> Goals </font>\n",
    "\n",
    "- We use the Python Enhancement Proposal 8 (PEP8) document  to provide guidelines and best practices on how to write Python code. \n",
    "- PEP8 addresses topics such as name conventions, code layout, indentation, comments, etc..\n",
    "- Make the code more readable, maintainable and sharable.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=\"red\">Code Lay-Out</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Indentation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Use 4 spaces per indentation level."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# YES\n",
    "def long_function_name(\n",
    "         var_one, var_two, var_three,\n",
    "         var_four):\n",
    "     print(var_one)\n",
    "\n",
    "# NO\n",
    "def long_function_name(\n",
    "     var_one, var_two, var_three,\n",
    "     var_four):\n",
    "     print(var_one)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- The closing brace/bracket/parenthesis on multiline constructs may either line up under the first non-whitespace character of the last line of list "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_list = [\n",
    "    1, 2, 3,\n",
    "    4, 5, 6,\n",
    "    ]\n",
    "result = some_function_that_takes_arguments(\n",
    "    'a', 'b', 'c',\n",
    "    'd', 'e', 'f',\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tabs or Spaces"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Spaces are the preferred indentation method.\n",
    "- Tabs should be used solely to remain consistent with code that is already indented with tabs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Maximum Line Length"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Limit all lines to a maximum of 79 characters.\n",
    "- For docstrings or comments, the line length should be limited to 72 characters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Blank Lines"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Surround top-level function and class definitions with two blank lines.\n",
    "- Method definitions inside a class are surrounded by a single blank line.\n",
    "- Use blank lines in functions, sparingly, to indicate logical sections."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- One import statement per line\n",
    "- Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants\n",
    "- Imports should be grouped in the following order:\n",
    "     1. Standard library imports.\n",
    "     2. Related third party imports.\n",
    "     3. Local application/library specific imports.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Module Level Dunder Names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Module level \"dunders\" (i.e. names with two leading and two trailing underscores) should be placed after the module docstring \n",
    "but before any import statements except from \\_\\_future\\_\\_ imports. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "   This is the example module.\n",
    "   This module does stuff.\n",
    "\"\"\"\n",
    "\n",
    "from __future__ import barry_as_FLUFL\n",
    "\n",
    "__all__ = ['a', 'b', 'c']\n",
    "__version__ = '0.1'\n",
    "__author__ = 'Cardinal Biggles'\n",
    "\n",
    "import os\n",
    "import sys  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=\"red\"> Comments </font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Use complete sentences.\n",
    "- Use two spaces after a sentence-ending period in multi- sentence comments, except after the final sentence.\n",
    "- Each line of a block comment starts with a # and a single space"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inline Comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- An inline comment is a comment on the same line as a statement.\n",
    "- Inline comments should be separated by at least two spaces from the statement.\n",
    "- They should start with a # and a single space"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documentation String"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Write docstrings for all public modules, functions, classes, and methods.\n",
    "- Docstrings should have  comments that describe what the method does.\n",
    "- Then triple quote that ends a multiline docstring should be on a line by itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"This is an example of docstring.\n",
    "\n",
    "The ending triple quote should be on a line by itself.\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=\"red\">Naming Coventions </font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Descriptive: Naming Styles"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- lowercase\n",
    "- lower\\_case\\_with\\_underscores.\n",
    "- UPPERCASE\n",
    "- UPPER\\_CASE\\_WITH\\_UNDERSCORES\n",
    "- CapitalizedWords \n",
    "- mixedCase\n",
    "- Capitalized\\_Words\\_With\\_Underscores"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Packages and Modules Names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Modules should have short, all-lowercase names.\n",
    "- Underscores can be used in the module name if it improves readability. \n",
    "- Python packages should also have short, all-lowercase names."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Class Names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Class names should normally use the CapWords convention."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function and Variable Names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Always use  **self** for the first argument to instance methods.\n",
    "- Always use **cls** for the first argument to class methods.\n",
    "- If a function argument's name clashes with a reserved keyword, it is generally better to append a single trailing underscore rather than use an abbreviation or spelling corruption.\n",
    "\n",
    "<B>class_</B> is better than **clss**. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Constants"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Constants are usually defined on a module level and written in all capital letters with underscores separating words."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "MINUTES_PER_HOUR = 60\n",
    "HOURS_PER_DAY    = 24\n",
    "DAYS_PER_WEEK    = 7\n",
    "MONTH_PER_YEAR   = 12"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=\"red\">Programming Recommendations </font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Return Statements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Either all return statements in a function should return an expression, or none of them should.\n",
    "- If any return statement returns an expression, any return statements where no value is returned \n",
    "  should explicitly state this as **return None**, and an explicit return statement should be present at the end of the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# YES\n",
    "def bar(x):\n",
    "    if x < 0:\n",
    "        return None\n",
    "    return math.sqrt(x)\n",
    "\n",
    "# NO\n",
    "def bar(x):\n",
    "    if x < 0:\n",
    "        return\n",
    "    return math.sqrt(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sequences"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- For strings, lists, tuples, use the fact that empty sequences are false."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#YES\n",
    "if not seq:\n",
    "if seq:\n",
    "\n",
    "# NO\n",
    "if len(seq):\n",
    "if not len(seq):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Boolean Comparison"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Don't compare boolean values to True or False using **==**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Yes:   \n",
    "if greeting:\n",
    "    \n",
    "# No:    \n",
    "if greeting == True:\n",
    "\n",
    "# Worse: \n",
    "if greeting is True:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=\"red\"> Exercise </font>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Apply the coding standards to the code (def_converter.py, temperature_converter.py) in the directory pyCode. You may want to use a Python GUI editor such as pyCharm."
   ]
  }
 ],
 "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}