The Little Manual of API Design (2008) [pdf]

When thinking about the API only, any one of your line implementations seems just as good as the other.

But if you also ask "which of these makes sense for the client application" that will likely narrow your options down.

Indeed, the parent PDF says that before even writing any code, write use cases. "The implementation should adapt to the user, not the other way around."

The right answer for a API to draw a line like you describe is to provide every possible way to draw a line since you never know which one the user wants to use. Granularity is one of the general five properties of every good API, of course it is not always good to provide all possible ways since it hurts compactness. The best I have ever heared about API design was a talk from Casey Muratori: http://mollyrocket.com/casey/stream_0028.html

Apropos of nothing much, back when I was coding primarily in Objective-C (incidentally, for cross-platform Linux and Windows, but not anything Apple) the form of the function call would give another much more expressive option. I'd write something like this:

  [drawline  from: A
               to: B];

Obviously, some people hate it.

When languages are consistent, they are much easier to learn. Spanish is fabulously regular, which helps many people learn it.

When a second language is similar to your native tongue, it is much easier. Swedish speakers have very little trouble learning Danish, but Turkish is a bunch harder, and Korean is _very_ tough.

My point here is that your example is difficult because it lacks any larger context. If you want your API to be easy to learn for Lispers, then s-expressions are going to be better. If the rest of your API uses verbs like "make-a-box" and "paint-the-background", then "make-a-line" is probably the right fit.

Design always works this way: it is defined by its users and its context. When you hit trouble like this, step back.

For your particular example QBasic was actually a nice way of writing it:

    LINE (a,b)-(c,d), colour

On the other hand, they went nuts with it and had ways of making rectangles with the same syntax, too:

    LINE (a,b)-(c,d), colour, B  ' Rectangle
    LINE (a,b)-(c,d), colour, BF ' Filled rectangle

If we're going to design our own syntax to draw lines, I'll add a few things to the host language: First, a "point" data type, and a "line" data type. Most language can do this already.

Then I'd add some special syntax to denote points. Like one of those:

  (a, b) -- ordinary tuple.  Of the shelf in ML and Haskel.
  [a, b] // may work in C and C++
  (a; b) // Alternative syntax

We also need an operator to draw the line. Possibly a triple dash:

  (a, b) --- (c, d)

And of course this can be combined together (here in my custom version of C):

  Point p = (a; b);
  Line  l = p --- (c; d);

Now we need a way to actually draw the line. As a side effect. It could be a procedure, but when there's one line, there will be others. So, we often need to draw a list of lines. This syntax might work:

  draw {
    p      --- (c; d);
    (e; f) --- (g;h);
    (g; h) --- p;
  }

The semantics would be what you'd expect, with the possible benefits of some optimisation (some constructors can be avoided, the data can be packed before we draw all the lines at once…)

---

Now If I get to really try that in a real-world project, I'll probably find many ways to improve this lousy design.

I guess the OP means something more like "HTML makes it easy to make mistakes like ..." which is true. I believe English is not his native language.

You are, presumably, already a developer, so you already understand nesting. Perhaps a better example that a beginner could find quite reasonable after learning about start and end tags:

   <u>Underlined. <b>Bold and underlined.</u> Bold only.</b>

Why shouldn't that work?

Iterative cycles take advantage of the regularity of change. APIs shouldn't change once public, hence the emphasis on Big Upfront Design. However, change still needs to happen so versioning comes into play.

Personally, when it comes to APIs, you can tell those that have been designed upfront rather than iteratively; they are generally better IMHO.

What I would advice is to design the API (public part) without considering the internal code (private part).

We often change our point of view on how to solve a problem (private part), but rarely the problem itself changes (public part).

Iterate away your (internal) architecture as much as you want, but when dealing with the API (your external world interface) make sure to put yourself in your user shoes.