APIs and ontologies?

[bugmagnet]

I have a number of COM DLLs which provide tools for scripters. The problem I've been having with them over the years has been finding a suitable naming scheme for the individual functions. For example, is it

• WriteFileAscii, or
• FileWriteAscii, or
• AsciiFileWrite, or
• AsciiWriteFile, or
• some other thing?

Is it Noun + Verb + Adjective or is there some other approach that would make things more obvious to the programmer? In the above, for instance, there's also a Unicode version, as well as Read. And conceivably as well as File there could be Socket or some other sink.

Does one normally identify what the result is going to be in the naming of the function? Returns can be, for example, Variant, VariantArray, String, Array of String, Number, Array of Number, Collection, etc. 

And, maybe finally, there's the question of whether one is Putting, Setting, Letting, Getting ...

Are there any standards that one might adhere to?

Kind regards,

Bruce (bugmagnet) 

[Aaron Korver]

Well Bruce,

I usually pattern my APIs like this

<Things that don't change> .....<Things that change alot>

So in your example, do you have a FolderWrite as well as a FileWrite?

In that case, "Write" changes the least so that is what starts, then File, then Ascii (assuming you can write to multiple formats).

The other strategy I use is to make the client tell me what it is doing.  So for example create the interface "WriteOperation".  Then pass it a "WriteContext" object.  In that object you configure that you want to write a "File" and you want it in "ASCII".  The Implementation can check that the context is passing proper config options and then just do its thing.  That way, the API won't change, but the object you pass it can evolve over time.  This keeps things backwards compatible.

Just my thoughts on the "ways to skin a cat".  

Thanks,

Aaron Korver

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[bugmagnet]

In that case, "Write" changes the least so that is what starts, then File, then Ascii (assuming you can write to multiple formats).

Nice idea. Shall have a think about that.

 

The other strategy I use is to make the client tell me what it is doing.  So for example create the interface "WriteOperation".  Then pass it a "WriteContext" object.  In that object you configure that you want to write a "File" and you want it in "ASCII".  The Implementation can check that the context is passing proper config options and then just do its thing.  That way, the API won't change, but the object you pass it can evolve over time.  This keeps things backwards compatible.

That's an intriguing idea. Thanks!

Kind regards,

Bruce.  

[Greg D]

Can you make a case for following the pattern of the API's written language?  IE, presuming English, the natural spoken order of the words would suggest the order.

Start with a minimal english statement of intent:
"I want to write an ascii file"

(Note that "I want to write a file with ascii encoding" isn't minimal, it's much wordier. Likewise, "I have an ascii file that I want to write.")

Pull the action out and crunch the words:
"WriteAnAsciiFile"

And eliminate superfluous articles:
"WriteAsciiFile"

[Pat Cappelaere]

I can make a case for a Story-based API (or Activity-based API).

Note: aren't we writing user stories after all?

so it would be {user} {verb} {object} {target}

define your verbs and objects …

Many verbs are getting standardized (see Activity Streams)

Then this will make good stories for your users to add to his TimeLine and NewsFeed (Facebook)

Pat.