Re: Defining APIs, best practices.

[Coda Highland <chighland@...>]

On Sat, Dec 15, 2012 at 12:41 AM, Andrew Starks <andrew.starks@trms.com> wrote:
>>> A small API that requires me to fill in my own code to cover the gaps
>>> is far better than a large one with a bunch of convenience methods
>>> that are there to "make life easy."
>>
>> This is a matter of opinion, and one I strongly disagree with. I DO
>> want a small, sufficient API to be available, but I also think that
>> the PURPOSE of software is to automate repetitive tasks. Computers do
>> repetitive tasks much better than humans do, so forbidding convenience
>> functions is counterproductive.
>>
> Fewer things that are more composable is, for me, a principle.
>
> If I have an API that provides methods to solve the problems at hand,
> the user can compose the API's structures to automate things in
> whatever way they want to.

Which is why I said the core elements need to be there. Don't keep the
primitive functions locked away in private API.

> If I (me) try to guess what will be helpful past the bare minimum, I
> know only two things, for sure:
>
> I'm wrong.
>
> I now have a big pile of wrongness that I now own and must maintain.

You're not ALWAYS wrong, though. Sometimes, yes, you're right, but
sometimes the atoms are TOO atomic and there's intended to be a
"recommended" way (or at least a "quick start" way) to get going. I
mean, if you're implementing a string library, you CAN implement
"replace all" as a composition of "find with start index",
"substring", and "concatenate", but who's actually going to want to do
that? And furthermore, why should every user of your API be forced to
reinvent that wheel (or google for someone else who has)?

There's also the case of times when you're not just "not wrong" but
"actively right" and users who would attempt to implement their own
"convenience" functions would in fact easily get it wrong.

If it's something illustrative enough to have as sample code in your
documentation, it's at least worth CONSIDERING if it's relevant enough
to be a precomposed function.

>>> Don't bother writing an API that you're not going to document.
>>
>> Counterpoint: Don't bother writing an API that doesn't document
>> itself. If you need to turn to the documentation, the function is
>> either not self-documenting enough or too complicated. (And sometimes
>> complicated functions have to happen, but it's better to avoid them
>> when possible.)
>>
>>> Documentation that looks like this:
>>>
>>> get_by_id()
>>> property_id, number
>>> ID number for the property
>>>
>>> Is not documentation.
>>
>> Yet that's exactly the kind of documentation you end up with if you
>> write good, self-documenting APIs with the long function names you
>> were describing.
>
> Yeah. That is very solid thinking and I don't think I know anyone who
> agrees with me on this. I've read code complete, as you probably have,
> and the argument is compelling.

Haven't read it, actually. Self-documenting code isn't something I've
ever had to formally study -- and in fact what formal studies I've
done haven't put any emphasis on it. (Maybe this is a flaw in the
classes I took.) It is, rather, something that has evolved naturally
out of USING well-written APIs and emulating them in my own.

> I think it is wrong, though, and it seems like an excuse. I think
> these things, mostly in light if unit testing. Unit testing gives you
> a contract that the code does what the tests test. These are great
> starting points for documentation.

If it's being used as an excuse not to write documentation, then
you're right that it's wrong. But how are you supposed to document
something like this without just repeating the obvious:

myString:append(otherString)

You'd write "Appends otherString to myString" or some variant thereof,
and if you need any other documentation for that then your function is
probably doing something that violates the principle of least
surprise.

Self-documenting code isn't mutually exclusive with unit testing,
either. They actually work very well together, because then your TESTS
read as good documentation of intent as well. If you can actually read
the unit tests, that makes them that much more likely to be CORRECT
tests.

> Simple-ness, named arguments, documentation and consistency are all
> driving at the thing in software that was pointed to as "the most
> important thing" by Steve Yegge: accessibility.
>
> You may have more sophisticated values or maybe your experience has
> concluded that your way gets you to accessibility.

I agree that accessibility is king, and it frustrates me to come
across an opaque API or a poorly-designed UI.

If I can't tell what an API does (even if it's just a coarse idea of
it) by looking at it, that's not accessible.

If I need to have the documentation open while writing code, that's
probably not accessible.

This bounces back to convenience functions: If a task requires
substantially more work to implement than it ought to, because you
have to assemble the atoms yourself, that's not really accessible (but
it's better than nothing).

> I just like to state things in absolutes because its fun. :)

And I like debating stuff because it's fun. :P

/s/ Adam