''' Purpose: introduce modules. the module defines two functions add() and
             negate().  they are available to other python files that
             import harb.py
   modules do not have executable code - no output when we run this
   only holds self defined functions
   modules must be imported into programs if those programs intend to use any functions in the modules
'''

# defining functions always start with the line
# def function_name( parameters_if_any ):
# indentations after this def statement will be the function body
#     must have at least 1 line of code that is not a comment
#     functions do something
#     you can call functions in multiple programs to do something repeatedly, instead of writing what's in the
#        function body multiple time

# functions ALWAYS RETURN something!
# if we have a return statement, then the function will return the value that follows the keyword return
# if we do NOT have a return statement, then the function will DEFAULT to return the keyword None

# parameters are placeholders within the function definition
#  you must know what you are intending to pass in
#  must know the type of the parameter (string, float, int, list, ....) even if it's not explicitly defined here
#  the order of the parameters matter and you need to know that
#     because when you use the function (invoke it), you must pass in the correct value with the correct type
#     and in the correct order
#  ex: let subtract( a, b ) be a function that does a - b and return the difference
#     subtract( 3, 4 ) is NOT the same as subtract( 4, 3 )
#     subtract( '3', 4 ) WILL crash because - is not defined for strings
#     subtract( 3, '4' ) and subtract('3', '4') same prob as above

# arguments are actual values that are pass into the function when we invoke it
#  can be variables that hold values or can be the values themselves


def add( a, b ) :              # function named add(), parameters named a and b
   ''' Returns value of a + b
   '''

   result = a + b              # compute value of interest

   return result               # function hands back its result



def negate( x ) :              # function named negate(), parameter named x
   ''' Returns inverse of x
   '''

   result = -x                 # compute value of interest

   return result               # function hands back the inverse