Comments on: Making APIs is hard

By: MARTIN

MARTIN — Thu, 05 Apr 2012 01:34:52 +0000

//”extend” can be confused with classical inheritance, you are not extending a class, you are simply copying properties from another object.
04 //”a”, “b”, “p” doesn’t describe what the parameters/variables are
05 function extend(a, b){
06 for(var p in b){
07 a[p] = b[p];
08 }
09 }
10
11 /* === descriptive names === */
12
13 //”mixIn” describes that properties are being copied from one object to another, other possible names: “aggregate”, “combine”, “merge”.
14 //”target” shows that base object is being augmented and that method doesn’t return/create a new object, using a name like “base” would be recommended if method returned a new object.
15 //”obj” is not really a good name but since “mixIn” and “target” already gives enough context and the function is so simple it is enough to understand that it is an object with properties that will overwrite `target` props. Other possible names: “extensions”, “extras”, “props”.
16 //”key” common abbreviation used for properties names in `for in` loops. “name” and “prop” are also common.
17 function mixIn(target, obj){
18 for(var key in obj){
19 target[key] = obj[key];
20 }
21 }

By: David Higgins

David Higgins — Fri, 30 Mar 2012 20:05:05 +0000

There is an art to writing docs. Writing API docs is a bit different, in that you offer a service, often at the expense of describing the innards of your program.

Often when I read API docs, I often find myself pondering where such things exist when you describe them.

For example:

Developer A writes: “Just include this module at the top of the document”

… My reaction is usually “What module?”

Simple as that. My advice when writing docs is; link everything together. Every word, or “term” you use, link it somewhere else, where you, the potential developer can read up more on that method / property.

Reading docs, at least for me, has always, and probably (sadly) will be a -Link-Hopping-Experience-

By: samantha silver

samantha silver — Thu, 02 Feb 2012 12:55:52 +0000

its not easy i agree with you 🙂

By: Facebook Developer

Facebook Developer — Thu, 19 Jan 2012 13:46:12 +0000

The APIs created by open source community and Google both seems to be very well documented and easy to understand and implement as compare to others, even facebook graphAPI is well documented and lots of help available over the net.

By: bernie

bernie — Mon, 16 Jan 2012 12:24:27 +0000

I’m using a very simple and easy to maintain naming. It’s based in namespaces to identify where in the application is located any method. In brief this can be something like this:

Static methods grouped by functionality or entity (for example a given social network):
AppFooTools = {};

AppTools.getFormattedDate = function () { ... };
Instantiable classes:
AppFooItem = function () { this.att1 = ''; this.att2 = ''; };


AppFooItem.prototype.init = function (p1, p2) {

  this.att1 = p1;

  this.att2 = p2;

};
(...)
item = new AppFooItem();

item.init("hello", "world");

By: Miller Medeiros

Miller Medeiros — Thu, 22 Dec 2011 13:26:30 +0000

jQuery isn’t exactly the best example about a good API, so many method overloads, conflicting names (.is, .not, .bind, .add, etc), single namespace, etc… But it is still “better” than “plain DOM”.

I wrote a post a couple months ago about how to name things: http://blog.millermedeiros.com/2011/07/naming-methods-properties-and-objects/

Cheers.

By: Randy Peterman

Randy Peterman — Thu, 22 Dec 2011 06:08:03 +0000

I once heard a teacher say something like, “Each domain of knowledge comes with a new vocabulary. It is expected that not everything can be expressed in elementary school vocabulary.” You shouldn’t make unnecessary vocabulary that is too complex, but can be represented with simpler ideas, but you should also not be afraid to create more descriptive vocabulary (new compound words for example) where it is useful.

API creation is very much about the language and vocabulary of a specific domain. You have CRUD in many APIs, but once you get into the nuance, it gets tricky because APIs shouldn’t change (See also the SOLID principles), but they should be extendable. This makes them more like a sky scraper than a spider web, hopefully.

This is good stuff and needs more attention within the programming community as a whole. Thanks for sharing your thoughts!