3

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.

Ius Klesar
  • 133
  • 1
  • 4
  • 1
    The "interface" is the "public facing bit - what a caller uses. i.e. the bit betwenn the paraens: `(` and `)` – doctorlove Nov 28 '17 at 17:23
  • 1
    The interface is just what the user of the function sees: the signature. Someone calling `circle` doesn't need to know the internal structure; they just need to know that it takes two arguments `t` and `r`, and that there should be a global(?) variable named `n` defined in the calling scope. – chepner Nov 28 '17 at 17:24
  • @chepner "The interface is just what the user of the function sees" - alright, but you follow this up by saying that they need to know that there should be a global variable named n defined in the calling scope. How would a user "see" this? And if they could somehow see it, how is not using n as a parameter "cleaner" than not using it as a parameter, if in the end they have to know that it's there. Your definition seems quite different from that of doctorlove? – Ius Klesar Nov 28 '17 at 17:26
  • Possible duplicate of [What is the definition of "interface" in object oriented programming](https://stackoverflow.com/questions/2866987/what-is-the-definition-of-interface-in-object-oriented-programming) – jmargolisvt Nov 28 '17 at 17:27

2 Answers2

7

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.

Martijn Pieters
  • 1,048,767
  • 296
  • 4,058
  • 3,343
  • "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." But how would somebody know this about a user-defined function like circle, or polygon? Do I have to explain that somewhere? Is that somehow built-in? – Ius Klesar Nov 28 '17 at 17:33
  • @IusKlesar: generally, 'the documentation'. The code itself can be the documentation, so you could expect the user to read the code, so put in a good docstring on the function that explains what it does. Python is highly introspectable, meaning that other tools can do the reading for you, so your IDE can show you the interface (including the docstring). – Martijn Pieters Nov 28 '17 at 17:35
  • "Ideally, you as a caller should not need to know about this implementation detail." right, but @chepner said (in a comment to my main question) that users need to know that there's an `n` in the calling scope (whatever a calling scope is)? So...they *do* need to know about the implementation? – Ius Klesar Nov 28 '17 at 17:35
  • @IusKlesar: but documentation can also be separate. How do you know what the `print()` function does? Hopefully you know to look that up in the [Python documentation](https://docs.python.org/3/library/functions.html#print). – Martijn Pieters Nov 28 '17 at 17:36
  • @IusKlesar: see the rest of my answer, where I specifically address why adding `n` to the interface is not a clean solution. If you add `n` as an argument to the `circle()` function, you are asking the caller to understand what `n` *does*. What does `n=10` mean vs `n=100`? That's messy interface design, the function should ideally just calculate a suitable value for `n`. – Martijn Pieters Nov 28 '17 at 17:37
  • Incredibly well-written answer by the way, one of the best I ever got across stack-platforms. Simple, accessible and above all, thorough (you really ticked all the boxes in my question). I just wanted to say a big, fat thank-you! I appreciate this a lot, especially after feeling overwhelmed by many of the more technical answers I found on the web. – Ius Klesar Nov 28 '17 at 17:38
1

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.

doctorlove
  • 18,872
  • 2
  • 46
  • 62