Hands on how to: add a section about pros and cons on separating or not...

Hands on how to: add a section about pros and cons on separating or not declarations and definitions.

Hands on how to: add a section about pros and cons on separating or not...
9a7c7886 · GILLES Sebastien · 01067627 · 9a7c7886
Commit 9a7c7886 authored 1 year ago by GILLES Sebastien
--- a/HandsOn/HowTo.ipynb
+++ b/HandsOn/HowTo.ipynb
@@ -49,7 +49,7 @@
    "\n",
    "First create a folder in which the executables will be built and initialize CMake here:\n",
    "\n",
-    "```\n",
+    "```shell\n",
    "mkdir -p build\n",
    "cd build\n",
    "cmake ..\n",
@@ -65,7 +65,7 @@
    "\n",
    "and if everything is alright you should see (in the case of the [first hands-on](../1-ProceduralProgramming/2b-hands-on.ipynb#EXERCISE-1:-Adding-a-loop)):\n",
    "\n",
-    "```\n",
+    "```shell\n",
    "0.65 ~ 1 / 2^1\n",
    "0.65 ~ 3 / 2^2\n",
    "0.65 ~ 5 / 2^3\n",
@@ -98,6 +98,109 @@
    "For more information about the Docker way please look the dedicated [README](README.md) (the one within the _HandsOn_ folder of the root directory)."
   ]
  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Declaration and definition"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We saw briefly [here](http://localhost:8888/lab/tree/1-ProceduralProgramming/4-Functions.ipynb#Function-declaration) and [there](http://localhost:8888/lab/tree/1-ProceduralProgramming/4-Functions.ipynb#Function-definition) what is the difference between the declaration and the definition of a function (and also from other stuff such as objects that we'll see in part 3).\n",
+    "\n",
+    "We'll explain in a [late notebook](http://localhost:8888/lab/tree/6-InRealEnvironment/2-FileStructure.ipynb) how to properly structure a project with several files, but for the hands-on the idea is not to bother with this and each exercise is fully present in one file (see above).\n",
+    "\n",
+    "Therefore, you are not exactly required to separate declaration and definitions, and we don't dictate the choice you should do. We can nonetheless give you the pros and cons of each approach:\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### No declaration - only definitions\n",
+    "\n",
+    "In this configuration, when you use a function you provide both the signature of the function and its implementation. For instance:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "void DisplayPowerOf2Approx(double value)\n",
+    "{\n",
+    "    ... // implementation is provided here\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The advantage is that when you need to modify the signature you only do it in one place.\n",
+    "\n",
+    "The drawback though is that if you're using such a function in another function, you must be sure it is already defined beforehand. \n",
+    "\n",
+    "So you might have to reshuffle the order of your functions in the exercises to ensure they are defined before use."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Declaration and definition"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This configuration is much closer to what you would do in an actual code.\n",
+    "\n",
+    "The idea is that at the beginning of the file you first place all the declarations:    "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "// Beginning of the file\n",
+    "void DisplayPowerOf2Approx(double value);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "and that after that you provide the actual definitions, e.g.:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "void DisplayPowerOf2Approx(double value)\n",
+    "{\n",
+    "    ... // implementation is provided here\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You should figure out the pros and cons by reading the alternate case: the drawback is that you have to modify the signatures at two locations if you do that, but you don't have to bother about the functions ordering in the definition part."
+   ]
+  },
  {
   "cell_type": "markdown",
   "metadata": {},

 %% Cell type:markdown id: tags:

 # [Getting started in C++](./) - [How to do the hands-on](./HowTo.ipynb)

 %% Cell type:markdown id: tags:

 <h1>Table of contents<span class="tocSkip"></span></h1>
 <div class="toc"><ul class="toc-item"><li><span><a href="#How-to-do-the-exercises?" data-toc-modified-id="How-to-do-the-exercises?-1">How to do the exercises?</a></span><ul class="toc-item"><li><span><a href="#Don't-do-the-hands-on-in-Jupyter-notebook!" data-toc-modified-id="Don't-do-the-hands-on-in-Jupyter-notebook!-1.1">Don't do the hands-on in Jupyter notebook!</a></span></li><li><span><a href="#Online-compilers" data-toc-modified-id="Online-compilers-1.2">Online compilers</a></span></li><li><span><a href="#On-your-local-machine" data-toc-modified-id="On-your-local-machine-1.3">On your local machine</a></span><ul class="toc-item"><li><span><a href="#How-to-compile-and-run-the-program?" data-toc-modified-id="How-to-compile-and-run-the-program?-1.3.1">How to compile and run the program?</a></span></li><li><span><a href="#For-each-exercise" data-toc-modified-id="For-each-exercise-1.3.2">For each exercise</a></span></li></ul></li><li><span><a href="#With-Docker" data-toc-modified-id="With-Docker-1.4">With Docker</a></span></li></ul></li></ul></div>

 %% Cell type:markdown id: tags:

 ## How to do the exercises?

 Hands-on are interspersed throughout the lecture, and are really recommended as it is a way to check you truly assimilated what was explained in the notebooks (in programming rather often things seem easy... until you try to do them by yourself!)

 There are basically three ways to do the exercises, but I will start with the one to avoid:

 ### Don't do the hands-on in Jupyter notebook!

 Jupyter notebooks are a great tool to provide a decent and interactive support for lectures, and we can really thank the [guys behind Xeus-cling](https://github.com/QuantStack/xeus-cling/graphs/contributors) for their amazing work to port C++ into an interpreter-like environment.

 However, it is clearly not an environment for direct development: the fact you need to restart the kernel and rerun all relevant cells each time you modify a function is extremely cumbersome during the trial-and-error that is often the writing of code.

 ### Online compilers

 [Coliru](https://coliru.stacked-crooked.com/) or [Wandbox](https://wandbox.org/) provides online compilers in which you may paste code, compile it and then run it.

 They are clearly the easiest way to go (except for the [hands-on related to file structure](../6-InRealEnvironment/2b-hands-on.ipynb) for which we will need to work locally).

 ### On your local machine

 This implies a _recent_ compiler is already installed on your machine and ready to use.

 I provide in the folder in which hands-ons are set a very basic and crude `CMakeLists.txt` that should provide compilation (at least on Unix systems).

 #### How to compile and run the program?

 First create a folder in which the executables will be built and initialize CMake here:

-```
+```shell
 mkdir -p build
 cd build
 cmake ..
 ```

 Now in this folder you may run `make` to build the executables.

 At first only `initial_file.cpp` is compiled into a `initial` executable.

 You may run it through:

 `./initial`

 and if everything is alright you should see (in the case of the [first hands-on](../1-ProceduralProgramming/2b-hands-on.ipynb#EXERCISE-1:-Adding-a-loop)):

-```
+```shell
 0.65 ~ 1 / 2^1
 0.65 ~ 3 / 2^2
 0.65 ~ 5 / 2^3
 ```

 Each time a change is made or a new file is added in `CMakeLists.txt`, you just need to run again `make` command.

 #### For each exercise

 The idea is to start from `initial_file.cpp` and modify it slightly in each exercise.

 You need therefore to copy this file and create a new executable; you have basically two options:

 * Using one file for all exercises in a given thematic. The pro is that you won't need to edit the CMakeLists.txt more than once, the con is that you don't keep the intermediate states of your work.
 * Use a file per exercise; when beginning a new one you need to:
    * Copy the former one into new cpp file, e.g. `cp exercise1.cpp exercise2.cpp`.
    * Edit the CMakeLists.txt and uncomment the relevant line, e.g. `add_executable(exercise2 exercise2.cpp)`

 I have done the latter but feel free to do the former if you wish.


 ### With Docker

 I also provide a [Docker](https://www.docker.com/) image in which a very basic Fedora environment is displayed.

 You may compile / run the code in a Docker container and edit your file in your computer environment with you favorite editor / IDE.

 The steps to compile are the same as presented in the previous section.

 For more information about the Docker way please look the dedicated [README](README.md) (the one within the _HandsOn_ folder of the root directory).

 %% Cell type:markdown id: tags:

+## Declaration and definition
+
+%% Cell type:markdown id: tags:
+
+We saw briefly [here](http://localhost:8888/lab/tree/1-ProceduralProgramming/4-Functions.ipynb#Function-declaration) and [there](http://localhost:8888/lab/tree/1-ProceduralProgramming/4-Functions.ipynb#Function-definition) what is the difference between the declaration and the definition of a function (and also from other stuff such as objects that we'll see in part 3).
+
+We'll explain in a [late notebook](http://localhost:8888/lab/tree/6-InRealEnvironment/2-FileStructure.ipynb) how to properly structure a project with several files, but for the hands-on the idea is not to bother with this and each exercise is fully present in one file (see above).
+
+Therefore, you are not exactly required to separate declaration and definitions, and we don't dictate the choice you should do. We can nonetheless give you the pros and cons of each approach:
+
+
+%% Cell type:markdown id: tags:
+
+### No declaration - only definitions
+
+In this configuration, when you use a function you provide both the signature of the function and its implementation. For instance:
+
+%% Cell type:code id: tags:
+
+``` C++17
+void DisplayPowerOf2Approx(double value)
+{
+    ... // implementation is provided here
+}
+```
+
+%% Cell type:markdown id: tags:
+
+The advantage is that when you need to modify the signature you only do it in one place.
+
+The drawback though is that if you're using such a function in another function, you must be sure it is already defined beforehand.
+
+So you might have to reshuffle the order of your functions in the exercises to ensure they are defined before use.
+
+%% Cell type:markdown id: tags:
+
+### Declaration and definition
+
+%% Cell type:markdown id: tags:
+
+This configuration is much closer to what you would do in an actual code.
+
+The idea is that at the beginning of the file you first place all the declarations:
+
+%% Cell type:code id: tags:
+
+``` C++17
+// Beginning of the file
+void DisplayPowerOf2Approx(double value);
+```
+
+%% Cell type:markdown id: tags:
+
+and that after that you provide the actual definitions, e.g.:
+
+%% Cell type:code id: tags:
+
+``` C++17
+void DisplayPowerOf2Approx(double value)
+{
+    ... // implementation is provided here
+}
+```
+
+%% Cell type:markdown id: tags:
+
+You should figure out the pros and cons by reading the alternate case: the drawback is that you have to modify the signatures at two locations if you do that, but you don't have to bother about the functions ordering in the definition part.
+
+%% Cell type:markdown id: tags:
+

 [© Copyright](../COPYRIGHT.md)