Re: Defining APIs, best practices.

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

Some opinions that I have about API writing that will sound
authoritative, but don't have a right to be ( I sound authoritative to
beat my own bad habits back):

Both set_enable[1] and enable are ambiguous.
(Assuming you want true as default)

local enabled = enabled == nil and true or (type(enabled) ~= "boolean"
and error(...) or enabled)

Other choice name candidates:
is_active
is_enabled

Generally, name your flags and booleans so that they read well in a
"if" statement:

if is_active then ...

Take advantage of good IDEs and use long and descriptive property
names. Do not abbreviate anything. There isn't a point to that.

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"}

Provide defaults wherever possible. Nothing sucks more than having to
type stuff that is almost always one way.

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

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.

In the same way, return nil when "nothing" is the answer, but never
when you didn't get what you needed to do what you were asked. That's
an error.

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

Don't bother writing an API that you're not going to document.

Documentation that looks like this:

get_by_id()
property_id, number
ID number for the property

Is not documentation.

I'm sure that with most of this, you have your own opinions and
experience and don't need mine. Just thought I'd share, because its
been something I've been thinking about, as well.


[1] are we Pascal? setEnable... Please. ;)

[2] I learned this at the Lua conference from Fabian at Sierra
Wireless, who's opinions on this topic are almost certainly more
informed than mine. It was an honor and privilege to have a beer with
him and everyone else at the conference.

-Andrew Starks
Tightrope Media Systems


sent from my toaster

On Dec 14, 2012, at 18:24, Rena <hyperhacker@gmail.com> wrote:

> On Fri, Dec 14, 2012 at 6:44 PM, Javier Guerra Giraldez
> <javier@guerrag.com> wrote:
>> On Fri, Dec 14, 2012 at 6:33 PM, Coda Highland <chighland@gmail.com> wrote:
>>> If and only if the function detects the difference between (nil) and
>>> (). If the function is called enable, and I call it as enable(), I
>>> would expect it to enable the object -- that is, the same as
>>> enable(true), not enable(false)! So it's messy.
>>>
>>> For this reason I prefer setEnabled(bool) over enable(bool), which
>>> also means the matching predicate is isEnabled().
>>
>> about semantics and names:
>>
>> i'd expect a  "enable()" function to always enable.  and a
>> "setEnabled()" to take a flag.
>>
>> no mess with "enable()==enable(nil)==enable(false)==disable()"
>>
>> --
>> Javier
>
> Personally, I feel the most Lua-like method is to provide a .enabled
> property via metatables, but that's not always the best idea, when
> overhead and complexity might be an issue. In that case I usually go
> with enable(x) means "if x then enable else disable end", and
> isEnabled() to check.
>
> --
> Sent from my Game Boy.
>