Re: Defining APIs, best practices.

[Andrew Starks <andrew.starks@...>]

On Dec 15, 2012, at 1:05, Coda Highland <chighland@gmail.com> wrote:

> On Fri, Dec 14, 2012 at 10:10 PM, Andrew Starks <andrew.starks@trms.com> wrote:
>>
>> Both set_enable[1] and enable are ambiguous.
>> (Assuming you want true as default)
>
> How is setEnabled ambiguous? (Use setEnabled and not setEnable if your
> predicate is called isEnabled -- be consistent with your tense!)
>

If you have setters/getters then you are right and I shouldn't have
come off as contradictory.

In the case of set/get, conveying a desired state that couldn't also
be an action might be even more clear, but I'm having trouble coming
up with a better example than yours.

>> Generally, name your flags and booleans so that they read well in a
>> "if" statement:
>
> Which is what I said too. (The generic term here is "predicate".

I stand corrected.

>
>> Never use ordered arguments for function calls to an API. What is the
>> point of the order ordered arguments? Is the third-ness of the third
>> argument to a method helpful to me? Is that more memorable than
>> saying:
>>
>> my_func{iPhone = "auto correcting type writer", writing = lua,
>> at_night = "is a pain in the butt"}
>
> It depends on the function. Positional parameters are more efficient
> when you need performance and less verbose when it's something you use
> a lot. You will find that named parameters are a common holy war, and
> in my PERSONAL opinion they're only really appropriate for a function
> with more than one optional parameter, and even then sometimes it
> makes sense to have BOTH positional AND named. (Python supports this
> effortlessly.)
>

Valid points. As we're arguing about rock and roll and not truth, (Rush RULZ)...

If you do some one way and some the other, your making a choice for
cleaner syntax over consistency. It's not a bad one, but generally, I
like one API to be one way.

An important exception would be where the API/library is using a
specific syntax as convenient sugar, such as with LPEG's V"rule"

My point is that an API used by someone else should favor "obvious"
and consistent over terse-ness and syntax flexibility.

>> Don't be cool with a table or nil when a boolean describes the
>> purpose. Ambiguity is never helpful because it often covers up two
>> errors (1: I'm always evaluating to "true", 2: because...)
>
> Considering how many functions are designed to return "nil, error" on
> error failure, it is occasionally convenient to allow nil and false to
> coincide. As with many maxims, it's not a blanket rule to be applied
> blindly, but a guideline that you should think about when you're
> making decisions.
>

When I'm consuming something I've made then there are lots of choices
to make. I might be catching errors in some kind of logging module.

Having an entire API that goes with nil, error is a reasonable choice.

Consistency would be key, to my thinking.

>> For the purposes of programming an API (or programming, generally)
>> "nil" is not a value, even if Lua says it is. It's nothing. I wish
>> this worked:
>>
>> local delete = function(variable)
>>   variable = nil
>> end
>>
>> It would be silly to do this, but delete(my_var) drives the intent
>> home[2]. You're not assigning. You're removing/deleting.
>
> Actually there is a way to pull this off using the debug library, but
> it's ugly as sin and horribly unperformant. (Pass the variable name as
> a string, loop over debug.getlocal until you find it, then use
> debug.setlocal to nil it.)
>
>> 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.

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.



>> 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.

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.

Like this conversation, docs without tests is a bunch of wishes,
postulation, opinions and what you think was true or  what was true at
some point.

With tests, the results of which could be integrated into some basic
documentation about the design and purpose of the API, you have a
pretty good idea that the code does what the docs say.

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 just like to state things in absolutes because its fun. :)

Good stuff, though.
>
> /s/ Adam
>