Guide_Sidenote_Parameters.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Side Note on Parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Don't use *args and **kwargs parameters without a very good reason.\n",
    "\n",
    "There _are_ valid use cases for [this kind of parameter notation](https://realpython.com/python-kwargs-and-args/).\\\n",
    "In particular `*args` comes in handy when there is an unknown number of equal typed arguments to be passed. E.g., the `pathlib.Path` constructor.\\\n",
    "But if the parameters are expected to be structured in any way, it is just a bad idea."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 2 6\n"
     ]
    }
   ],
   "source": [
    "def f(x, y, z):\n",
    "    return x + y + z\n",
    "\n",
    "# bad in most cases\n",
    "def g(*args, **kwargs):\n",
    "    x = args[0]\n",
    "    y = kwargs['y']\n",
    "    s = f(*args, **kwargs)\n",
    "    print(x, y, s)\n",
    "\n",
    "g(1,y=2,z=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 2 6\n"
     ]
    }
   ],
   "source": [
    "# usually just fine\n",
    "def g(x, y, z):\n",
    "    s = f(x, y, z)\n",
    "    print(x, y, s)\n",
    "\n",
    "g(1,y=2,z=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Decrease the number of parameters.\n",
    "\n",
    "Though CLIMADA's pylint configuration `.pylintrc` allows 7 arguments for any method or function before it complains, it is advisable to aim for less.\\\n",
    "It is quite likely that a function with so many parameters has an inherent design flaw.\\\n",
    "\n",
    "There are very well designed command line tools with innumerable optional arguments, e.g., `rsync` - but these are command line tools.\n",
    "There are also methods like `pandas.DataFrame.plot()` with countless optional arguments and it makes perfectly sense.\n",
    "\n",
    "But within the `climada` package it probably doesn't.\n",
    "\n",
    "#### _divide et impera!_\n",
    "Whenever a method has more than 5 parameters, it is more than likely that it can be refactored pretty easily into two or more methods with less parameters and _less complexity_:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "f does many things with a lot of arguments: (1, 2, 3, 4, 5, 6, 7, 8)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "36"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def f(a, b, c, d, e, f, g, h):\n",
    "    print(f'f does many things with a lot of arguments: {a, b, c, d, e, f, g, h}')\n",
    "    return sum([a, b, c, d, e, f, g, h])\n",
    "    \n",
    "f(1, 2, 3, 4, 5, 6, 7, 8)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "f1 does less things with fewer arguments: (1, 2, 3, 4)\n",
      "f2 dito: (5, 6, 7, 8)\n",
      "f3 dito, but on a higher level: (10, 26)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "36"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def f1(a, b, c, d):\n",
    "    print(f'f1 does less things with fewer arguments: {a, b, c, d}')\n",
    "    return sum([a, b, c, d])\n",
    "\n",
    "def f2(e, f, g, h):\n",
    "    print(f'f2 dito: {e, f, g, h}')\n",
    "    return sum([e, f, g, h])\n",
    "\n",
    "def f3(x, y):\n",
    "    print(f'f3 dito, but on a higher level: {x, y}')\n",
    "    return sum([x, y])\n",
    "\n",
    "f3(f1(1, 2, 3, 4), f2(5, 6, 7, 8))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This of course pleads the case on a strictly formal level. No real complexities have been reduced during the making of this example.\\\n",
    "Nevertheless there is the benefit of reduced test case requirements. And in real life real complexity _will_ be reduced."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.7.3 64-bit ('climada': conda)",
   "language": "python",
   "name": "python37364bitclimadaconda2bcabf5424a143ed8fd9177a65a9f185"
  },
  "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}