CODEWITHSUNDEEP
pythonfunctioninterface
Ius Klesar
Ius Klesar

Reputation: 133

What is a Function Interface (in Python)?

In Allen Downey's "Think Python, version 2.0.17" for Python 2.x, Downey has this to say about a function's interface:

The interface of a function is a summary of how it is used: what are the parameters? What does the function do? And what is the return value? An interface is “clean” if it is “as simple as possible, but not simpler. (Einstein)”

I don't get this at all. Is an interface a written summary, like a docstring, that is appended to the function somewhere? Or is it something else entirely?

I'm a complete programming beginner, so I don't have a lot of context to draw on. I can't find any explanations that I can understand at my current (very low) level!

Quick example (though not strictly necessary for answering the question): Downey talks about drawing circles (in the context of Turtleworld). His function is 

def circle(t, r):
    circumference = 2 * math.pi * r
    n = 50
    length = circumference / n
    polygon(t, n, length)

in which t is a turtle from Turtleworld (he calls it Bob), and r is the radius of the circle to be drawn. Polygon is a function that takes the turtle, the number of sides n of the polygon and length (of its sides) as arguments, and draws a polygon with those specs. With sufficiently high n, this looks like a circle.

He then comments:

One limitation of this solution is that n is a constant, which means that for very big circles, the line segments are too long, and for small circles, we waste time drawing very small segments. One solution would be to generalize the function by taking n as a parameter. This would give the user (whoever calls circle) more control, but the interface would be less clean.

Again, what interface? What is an interface? Alright, let's roll with it for a second.

In this example, r belongs in the interface because it specifies the circle to be drawn. n is less appropriate because it pertains to the details of how the circle should be rendered. Rather than clutter up the interface, it is better to choose an appropriate value of n depending on circumference:

def circle(t, r):
    circumference = 2 * math.pi * r
    n = int(circumference / 3) + 1
    length = circumference / n
    polygon(t, n, length)

What? You don't want to clutter up the interface (whatever that is), so you...clutter up the interface? Or the function? Or the body of the function? I mean, I don't know what an interface is, but whatever it is - this solution only looks like it cluttered up the whole function even more, instead of just adding a parameter.

And, seeing as I haven't encountered a written summary of how the function is used anywhere so far, I'm starting to think my interpretation of Downey's function interface definition is all wrong.

Again, this is only an example, and I'd like to stress that I would like to understand what a function interface is in general, not just pertaining to this concrete situation. But this example is a good start, I think.

Upvotes: 3

Views: 10918

Answers (2)

doctorlove
doctorlove

Reputation: 19252

The author would appear to be talking about the function signature.

def add(x, y):
   pas ##some implementation here

tells you the function takes two things. You can't see what happens inside from this. If you look at the implementation you can see what happens inside.

Why does this matter? That's a different question - but if a function takes lots of parameters it can get confusing to use.

Upvotes: 1

Martijn Pieters
Martijn Pieters

Reputation: 1122242

The interface is what everybody else sees. When someone has to use this function, they have to know the name, the arguments it accepts, and what kind of result it will produce.

To give a different example: You probably know by now what the print() function will do. You don't have to know how that function works, all you know is what it'll do when you call it, and you know what kinds of things you can pass to it. All the things you need to know to use the print() function is the interface.

You used the concept in your question too. You explained to us what the polygon() function does:

Polygon is a function that takes the turtle, the number of sides n of the polygon and length (of its sides) as arguments, and draws a polygon with those specs.

When you did that, you described the interface of that function.

Now, why does adding n as an argument to circle() clutter up the interface? Because you as a user will now have to understand what value you need to give n. And to understand that you need to know more about how the actual implementation draws circles. Ideally, you as a caller should not need to know about this implementation detail. You just wanted a circle, why can't the function just do that, why does in need to know how many segments are involved.

What does and does not make a clean interface is subjective, something you build a sense for as you write software. I wouldn't worry too much about this just now.

Upvotes: 7

Related Questions