13-programming-style.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5937be8e-09e7-427a-a496-c5744127b16f",
   "metadata": {},
   "source": [
    "# Programming Style"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b59583f-4e51-4bbb-beb7-075f63003e54",
   "metadata": {},
   "source": [
    "## Coding style\n",
    "\n",
    "A consistent coding style helps others (including our future selves) read and understand code more easily. Code is read much more often than it is written, and as the [Zen of Python](https://www.python.org/dev/peps/pep-0020) states, “Readability counts”. Python proposed a standard style through one of its first Python Enhancement Proposals (PEP), [PEP8](https://www.python.org/dev/peps/pep-0008).\n",
    "\n",
    "Some points worth highlighting:\n",
    "- document your code and ensure that assumptions, internal algorithms, expected inputs, expected outputs, etc., are clear\n",
    "- use clear, semantically meaningful variable names\n",
    "- use spaces, not tabs, to indent lines (tabs can cause problems across different text editors, operating systems, and version control systems)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6bd69d7-757a-47b8-bc1a-b546f222eefb",
   "metadata": {},
   "source": [
    "## Follow standard Python style in your code.\n",
    "\n",
    "- [PEP8](https://www.python.org/dev/peps/pep-0008): a style guide for Python that discusses topics such as how to name variables, how to indent your code, how to structure your import statements, etc. Adhering to PEP8 makes it easier for other Python developers to read and understand your code, and to understand what their contributions should look like.\n",
    "- To check your code for compliance with PEP8, you can use the [pycodestyle application](https://pypi.org/project/pycodestyle/) and tools like the [black code formatter](https://github.com/psf/black) can automatically format your code to conform to PEP8 and pycodestyle (a Jupyter notebook formatter also exists called [nb_black](https://github.com/dnanhkhoa/nb_black)).\n",
    "- Some groups and organizations follow different style guidelines besides PEP8. For example, the [Google style guide on Python](https://google.github.io/styleguide/pyguide.html) makes slightly different recommendations. Google wrote an application that can help you format your code in either their style or PEP8 called [yapf](https://github.com/google/yapf/).\n",
    "- With respect to coding style, the key is _consistency_. Choose a style for your project be it PEP8, the Google style, or something else and do your best to ensure that you and anyone else you are collaborating with sticks to it. Consistency within a project is often more impactful than the particular style used. A consistent style will make your software easier to read and understand for others and for your future self."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a452c7d9-dbeb-4752-9791-b80f9b566a22",
   "metadata": {},
   "source": [
    "## Use assertions to check for internal errors.\n",
    "\n",
    "Assertions are a simple but powerful method for making sure that the context in which your code is executing is as you expect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2cf0561a-6694-4d36-a07b-99c65ee4e358",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def calc_bulk_density(mass, volume):\n",
    "    '''Return dry bulk density = powder mass / powder volume.'''\n",
    "    assert volume > 0\n",
    "    return mass / volume"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8790d866-dafd-4fb1-b2d9-f4307e16e2f8",
   "metadata": {},
   "source": [
    "If the assertion is `False`, the Python interpreter raises an `AssertionError` runtime exception. The source code for the expression that failed will be displayed as part of the error message. To ignore assertions in your code run the interpreter with the ‘-O’ (optimize) switch. Assertions should contain only simple checks and never change the state of the program. For example, an assertion should never contain an assignment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81e00103-78d2-4b39-9b79-b4a4595d7105",
   "metadata": {},
   "source": [
    "## Use docstrings to provide builtin help.\n",
    "\n",
    "If the first thing in a function is a character string that is not assigned directly to a variable, Python attaches it to the function, accessible via the builtin help function. This string that provides documentation is also known as a `docstring`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8697c2e5-0dbc-44fb-829a-fd6e7a171cad",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def average(values):\n",
    "    \"Return average of values, or None if no values are supplied.\"\n",
    "    \n",
    "    if len(values) == 0:\n",
    "        return None\n",
    "    return sum(values) / len(values)\n",
    "\n",
    "help(average)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ded6818b-bed0-4dbe-a078-74c6d5048e71",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}