In this activity you learn how to place functions you created yourself into your own library (we call your library your "toolbox", and you can think of the functions as the tools you collect and store in your toolbox).

Asking for a Graphic

Assume you have a friend who does not see the figure below:

Did you just say Olaf?? Olaf the snowman? That master of decomposition and composition?

What's Olaf made of? What's a snowman made of? Specifically, a two-dimensional simplified graphic of a snowman? Circles! At least two, one above the other!

So, let's get going and prepare to create some circles.

Defining (or Importing!) a Function to Conveniently Create Circles

We would like to use a function that can easily create a circle. If you just completed the "Circles" activity, you created such a circle function.

But we need that function right here. And right here it doesn't exist. What to do?

We have three choices:

1. Rewrite a circle function here
2. Copy the code defining a circle function we wrote somewhere else, and paste it here
3. Be clever

You said "be clever", didn't you? But at the same time you thought that option 2, copy-paste, was what you'd actually do, right?

We agree, rewriting code is work. And we don't want to have to work twice! So option 1 is out.

Code Clones are BAD

Copy-pasting code is much less work! But it's bad. It's a kind of "code smell". Copy-pasting code leads to multiple copies of the same code (also known as "code clones"). And if your code contains code clones, it stinks! It smells so bad, other programmers will stay away from you!

Why is it bad to copy and paste code? Doesn't it reduce work? Well, it might seem to, but in the longer term it almost always generates more work. The cost of copying code can be immense. It can be so bad that projects fail, systems are full of bugs, and airplanes crash.

Why that? Now, that is a good question! Let's hold that thought and defer a more thorough discussion to a future activity. For now, just quickly: if you copy your code, you end up with multiple clones. If you had a bug in the original, you now have multiple bugs (and if you end up finding one, you might fix that but not all its clones). Moreover, if you have to modify the functionality or clean up your code, you now have to do that for each clone. And how do you know how many clones of which pieces of code you created over time? It's a nightmare. Just don't do it!

Collecting Tools for Your Toolbox

So, let's go back to where you already implemented a circle function. That's probably in the Circles activity. In there, find the code cell that defines the circle function, and click on the little toolbox icon in its bottom right.

A dialog should pop up that guides you through the steps of adding your circle function to your toolbox. Once you complete that process, come back here, and you will see the circle function under "My Toolbox" in the left sidebar. It's always going to be there, and you can use it in any activity you want.

If you click on any of your toolbox functions in the left sidebar, you get a popup with the signature of your function (the parameters it takes, the return value it produces), with a code example you can run (really, your code example, which you wrote when you put the function in your toolbox) to understand (or remember) what your function does.

Using Tools from Your Toolbox

Now let's import your circle function, and draw a yellow circle:

Let's Build a Snowman

Let's define a function that can create a snowman. We want it to be somewhat flexible: it should be possible to specify the diameter of the head and of the body.

Implement the snowman function by calling the circle function you just imported above. Assume that in our world, snow is very clean, so snowmen are created in pure white.

If all works well, you should see white snowman on an almost white background. Can you barely see it? You can hover over the white area with your mouse, and the background behind the snowman turns into a grey checkerboard pattern. This way, your snowman should stand out a bit more.

Dusty Snow

Did you know that in Switzerland and across Europe the snow sometimes turns yellowish or even reddish? That's because of dust getting blown from the Sahara desert in Africa across the Mediterranean Sea, all the way into the Alps! Let's see how our snowman looks like after being coated by a bit of Sahara desert dust.

Modify the above code cell:

• Import the rgb_color function
• Define a name snow_color and assign it a orange-ish color you create (e.g., with rgb_color(255, 245, 210))
• Replace the use of the name white with snow_color
• Remove white from the imported names

Changing the color of the snowman required you to modify the snowman function. Why? Because the snowman function does not have a parameter where you could pass in the snow color. When we originally created the function, we assumed the snow would always be perfectly white. We did not foresee that desert sand dust would get blown from one continent to another and end up tainting the white snow.

When creating a function, it's up to us to decide what is fixed and what is flexible: for the flexible aspects, we want to introduce parameters, so whoever later calls our function can provide the desired values.

For our snowman, let's keep the snow color fixed.

Defining Names Within a Function

You may have noticed that we defined two names, inside our snowman function, to refer to the head and the body. This allowed us to write the quite readable expression above(head, body) to compose our snowman from the two circles known by those names.

Those two names are local to our snowman function. Code that sits outside the function will never know the two names exist. Really, code outside the snowman function should not have to worry about the fact that a snowman was composed from a head and a body.

Is Our Snowman Worthy of Being Reused?

If you wanted to, you could store your snowman function in the toolbox, too. Just click the tools button at the bottom of the above code cell. However, you may want to not do that. Why? Is this snowman function really worthy of a place in your toolbox? Are you really going to reuse it somewhere else? Isn't it a bit too specialized? If you are going to compose some kind of winter landscape, with snowballs, snowmen, sleds, skis, and snowboards, would this specific snowman function be something you'd want to call? If yes, go ahead, and store it in your toolbox (you can always remove it later). If no, keep your toolbox small and sweet, and reserve it for more generally useful functions (like, a function to create a square).

What You Learned

You composed a simple snowman by placing two circles above each other.

Much more importantly, you learned how to create and use your own library! Your toolbox.

While collecting lots of tools just for the purpose of growing one's collection may be fun (do you collect postage stamps? shoes? cars? clothes? planes?), your toolbox is not just a status symbol!

Your toolbox is useful, and it will make your life so much easier in the future! Why? Because you can import any of the functions from your toolbox and use them to do their work, anywhere you want! All you need is access to your toolbox. And within this web site, you always have access to your toolbox! And if you want to use it outside this web site, you can simply export an activity as a Python file, and your toolbox will be included in your download.