added some pass by reference and value examples in C++ but need the a…

…ll clear first. TODO: come back to this after the sign off.

docs/functions/intro-to-functions.md

@@ -46,10 +46,34 @@ Now we've made the code take in an arbitrary number of arguments and add them al
     Don't worry if much of this feels a little advanced for you right now, much of this is broken down in the later sections and explained in greater detail. It's only important that you understand that these principles exist and very roughly how they work at this stage.
 
 ## Modularity 
-The idea of modular programming lends itself to the idea that each function contains all of the code required to do a single job, and then every time you need to do that job again the function is called. If you think about how a character in a computer game is controlled, every time the character turns left it must call a turn left function. The same if it needs to jump or run backwards, directional animations and everything that makes a game run, all could be their own independent functions containing all the code to do each specific job. Consider this code:
-
-
-
+The term modular programming lends itself to the idea that each function contains all of the code required to do a single job, and then every time you need to do that job again the function is called. If you think about how a character in a computer game is controlled, every time the character turns left it must call a turn left function. The same if it needs to jump or run backwards, directional animations and everything that makes a game run, all could be their own independent functions containing all the code to do each specific job. Consider this pseudo code:
+
+``` python
+    # outline of a modular program
+    def open_file():
+        <code that opens files>
+        <code that opens files>
+        <code that opens files>
+    
+    def process_file_data():
+        <code that reads files>
+        <code that reads files>
+        <code that reads files>
+    
+    def close_file():
+        <code that closes files>
+        <code that closes files>
+        <code that closes files>
+    
+    open_file()
+    process_file_data()
+    close_file()
+```
+
+In this pseudo code, you can see that we have three functions all doing different jobs. Each one of the functions can contain code for the testing and for completing the steps required to do the job for which its named. In this way, you create modular code that can be used later in the program or exported into other projects, because you can call the function into another file. You can find more information on modules in the modules section [here](../modules/README.md). 
+
+
+{{ todo("remove this outline, for guide only.") }}
 ## Outline
 outline user defined
     - abstraction and reusability 

docs/functions/user-functions/README.md

@@ -12,5 +12,11 @@ def name_of_function(passed_variable):
     <indented even across>
     <multiple lines.>
 ```
-The contents of the function is always indented to show that it belongs to the function definition above it. 
+The contents of the function is always indented to show that it belongs to the function definition above it. Python then knows that this is the local scope of that function and looks there first for any variables, functions or data you might be trying to use in the function. The passed_variable placeholder can be one or more variables that are passed to the function so they can be used. These are known as function arguments, and are how we can move data between one function and another. 
+
+!!! hint
+    Understanding how data moves between functions is an important part of programming, as side effects can happen when you don't know what's happening behind the scenes. Make sure you feel solid with the next concepts as they can change depending on the programming language and is the starting point for reducing bugs in code and secure programming. 
+
+## Passing-by-value and Passing-by-reference 
+These concepts are two different ways we pass variables to functions in programming. When we pass a value by reference 
 

docs/functions/user-functions/example-2.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# example-2.py
+# showing pass by reference 
+var = 20 
+print("Initial variable value and object number:")
+print(var)
+print(id(var))
+
+def pass_by_reference():
+    global var
+    print("Initial ")
+    print(id(var))
+    var += 20
+    print(var)
+    print(id(var))
+
+pass_by_reference()
+print(var)
+print(id(var))
+
+def pass_by_value(var):
+    total = var
+    total = total + 20
+    print(total)
+    print(id(total))
+    return total
+
+pass_by_value(var)
+print(var)
+print(id(var))

docs/functions/user-functions/example-pass-by.cpp

@@ -0,0 +1,42 @@
+#include <iostream>
+using namespace std;
+
+// C++ prototypes 
+void pass_by_reference(int &var_1);
+void pass_by_value(int var_1);
+
+// example-pass-by.cpp
+// Illustrating pass by reference and value 
+// using C++ 
+
+// Function declarations
+void pass_by_reference(int &var_1)
+{
+    var_1 = var_1 + 5;
+    cout << var_1 << "\n";
+}
+
+void pass_by_value(int var_1)
+{
+    var_1 = var_1 + 10;
+    cout << var_1 << "\n";
+}
+
+// Program entry point
+int main ()
+{
+    int var_1 = 20;
+    cout << "The initial value of var_1 is: " << var_1 << "\n";
+
+    // This preserves the memory address and it 
+    // will keep the value.
+    cout << "This is after it's passed by reference:" << "\n";
+    pass_by_reference(var_1);
+    cout << var_1 << "\n";
+
+    // This doesn't preserve the memory address 
+    // and passes a copy of the value
+    cout << "This is after it's passed by Value." << "\n"; 
+    pass_by_value(var_1);
+    cout << var_1 << "\n";
+}