Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I've read a blog post called Blogging with Noir, and I was honestly surprised that the author uses java.jdbc instead of libraries like Korma which I found surprising. What are the advantages of writing SQL queries in your code instead of letting tools do it for you?
I guess it is for the usual reasons that you might choose to use an API directly in Clojure rather than use a wrapper:
Existing knowledge: you already know the JDBC well and know that it will get the job done, why spend time learning a new abstraction unless there is a clear advantage?
Uncertainty - does the library have all the features you need? Will it continue to be maintained and implement new features in the future?
Stability - the wrapper may not yet be mature, so you run the risk of your code having to change if breaking changes occur / bugs are discovered.
Completeness - the wrapper may not (yet) encapsulate all of the functionality of the original API that you need
Overhead - sometimes extra layers of abstraction add a performance overhead that you don't need/want
Extra dependency - adds complexity to your build, and conceptual overhead in terms of the number of abstractions you need to keep in your head.
Ultimately it's a trade-off - the above are reasons that you might want to use the underlying API, but there are equally good reasons that you may choose to use the wrapper:
More idiomatic - a wrapper library is likely to give you much cleaner, more elegant code than a Java-based API (particularly if the Java API is imperative/stateful). You have to admit that Korma is pretty elegant!
More composable - Clojure wrappers tend to adopt a functional style, which leads to easy composability with other clojure code / libraries.
New features - often Clojure wrappers add extra functionality that the original API does not posess (for example, look at the data binding functionality added on top of Swing by Seesaw)
Korma IMO isn't nearly ready to be used as a full replacement for SQL. It's definitely handy, but right now a lot of my queries have (raw "...") snippets in them, and for more complicated stuff all the main querying is done inside SQL views which are then selected on via korma.
The main alternative, ClojureQL, doesn't even work with Clojure 1.3+
In short, it's hard to abstract SQL, and Korma - even though it tries to be minimal, meaning you still have to understand SQL pretty well to use it - isn't finished.
I can think about two reasons:
Almost everybody knows SQL, almost nobody knows Korma
This is a guess, because I do not know Korma myself, but raw SQL is sometimes suitable or even necessary if you want to do something specific like features that are only present in a particular database
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
I am planning on putting up a web service, or some other service exposed over the internet. I would like to create an API for applications to interact with this service. I would like the API to be usable in different languages, such as Java, C++, C#, or PHP. How can I maintain one code base for my API, but distribute nice packaged binaries for all these languages? Also, I may want to consider this could be cross platform as well.
Update 1
I'm early days on Web Services, but I
think one of the key points is that
lots of tooling supports the
implementation of clients based on the
description of the service like WDSL.
I've not delivered any client-side
software with anything I've done, I
expect any user to be able to build
their own clients suited to their
needs. --Brabster's Answer
I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?
Update 2
As far as expecting the client that is
using your API to do anything, you
can't! There is nothing you will be
able to do to ensure that the consumer
of the API will do anything right.
That's why robust error handling is so
important. You must check and double
check any and everything that comes
from the client. You must always be
suspicious of it, and even assume that
it is malicious. There really is no
good way around that fact. --Ryan Guill's Answer
My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.
Update 3
I have accepted Ryan Guill's answer. I think the general idea is that I need to expose a network service of some sort, with the lowest barrier to the client. That way anyone can connect. Then just have all my code run on the server. That seems to be accepted as the only want to really achieve the platform and language independence I am after.
Thanks for all the input.
I would use a REST API, similar to the way Flickr's API works: http://flickr.com/services/api/
It is fairly simple to create and maintain, the biggest downsides are that it takes a lot of documentation (but pretty much any way you do an API will have this issue) and that robust error handling is a must.
But in my opinion, it's the best way to create an API that is the closest to cross platform/cross language.
More information here: http://www.xfront.com/REST-Web-Services.html
Update: The submitter added the following to the post:
I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?
I personally do not like using SOAP (using a WSDL). There is a lot of inherent overhead to using SOAP, both on the server and the client. I think that is why you see more and more public API's being written using REST. It really lowers the barrier to entry to the lowest common denominator, allowing anything that can use basic HTTP (GET and POST (also PUT and DELETE for the "proper" way of doing it)) to use the API.
Some more examples of public API's written using REST: twitter, vimeo, Google
As far as expecting the client that is using your API to do anything, you can't! There is nothing you will be able to do to ensure that the consumer of the API will do anything right. That's why robust error handling is so important. You must check and double check any and everything that comes from the client. You must always be suspicious of it, and even assume that it is malicious. There really is no good way around that fact.
Update 2: the submitter added the following to the post:
My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.
You can certainly do this, but that is only going to work for .NET languages, meaning that your cross-platform and cross-language benefits are out the window. And still, in the end, are you really preventing anything? The developer is going to either use your remote API, or your local DLL or Assembly. Either way, he is going to have to know how to use it and use it right, otherwise you are going to throw an error. All you are really doing is changing where the errors get thrown from. Which may be important to you (if so, mention why) but really isn't changing anything in the equation.
But you are somewhat correct in saying REST is kind of like web-services without the SOAP. Technically REST is web-services too, its just that web-services have come to generally mean SOAP. It really is a different way of achieving the same thing. The biggest differences are though that it takes more programming and thought on your side (and potentially more programming on the client side) but you trade that for robustness, less overhead in both the consumer and the server, and the widest possible audience for the API. It really is the lowest common denominator.
I'm early days on Web Services, but I think one of the key points is that lots of tooling supports the implementation of clients based on the description of the service like WDSL.
I've not delivered any client-side software with anything I've done, I expect any user to be able to build their own clients suited to their needs.
If you check out the flickr API as suggested by one of your other answers, I don't think they supply client side code, other people have built and contributed client side stuff.
I suggest writing the API in the Haxe programming language so that the source code can be directly translated to all the programming languages you mentioned. The Haxe programming language can be translated (or "trans-compiled") to all of the programming languages that you mentioned in the original post, as well as a few others.
Simple answer, no.
Complex answer: create an API and compile it to a COM dll. Then, just build the wrapper code for the languages that can't handle that.
Simple answer #2, make the original service so trivial, or so universally acceptable, as to not require an API (I usually implemented this through server-side database polling. Ugly but any language that can access a database can utilize the program).
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Interface Builder can be used for basic dependency injection in a Cocoa app, but is anyone aware of more complete dependency injection frameworks for Objective-C/Cocoa for when you don't want to instantiate objects in a NIB file?
Edit
To clarify, I recognize that IB can be used for basic DI, but I'm looking for a framework with more complete functionality, including separate production and testing configurations, along the lines of Groovy or Springs.
objection by AtomicObject. It is molded in the image of Guice.
I'll go out on a limb and speak on this. Dependency injection as described by the top answer doesn't address the core issue that those seeking to use it are having. We'd like a means of development where component A does not directly instantiate or reference component B. Component A is bound by protocol to component B and is not referenced at all by component A. This allows component B to be replaced at anytime without ever touching component A. I down voted but I will research your references as it seems there are a few who agree with you. I'm not trying to debate, just looking to learn. I'd like to understand more about the "nope you don't need to do that" approach.
I think you'll find that you don't need it in late-binding languages like Objective C, Ruby, Lisp and so on. Like Jamis' revelation that he was going down an overly complex path when he tried to build needle, a DI framework for Ruby- Net::SSH revisited.
Here are some links that will hopefully give you some sample code to do similar things in Objective C. With categories you can essentially change any class's behavior at runtime. See Mac Developer Tips – Objective-C: Categories and the Cocoa API docs on categories. Essentially you don't need some central place to ask for "the thing that does x" that is configurable, because you can just instantiate TheThingThatDoesX directly and if something else needs to change/hook into that behavior it can use categories.
Typhoon
Almost one year ago, I released: https://github.com/typhoon-framework/Typhoon
The Typhoon-website lists the key features. A quick summary:
Non-invasive. No macros or XML required. Uses a powerful Objective-C runtime approach.
Makes it easy to have multiple configurations of the same base-class or protocol.
No magic strings - supports IDE refactoring, code-completion and compile-time checking.
Supports injection of view controllers and storyboard integration.
Supports both initializer and property injection, plus life-cycle management.
Powerful memory management features. Provides pre-configured objects, without the memory overhead of singletons.
Excellent support for circular dependencies.
Lean. It has a very low footprint, so is appropriate for CPU and memory constrained devices.
Battle-tested - used in all kinds of Appstore-featured apps
An internationally distributed core team (we even monitor StackOverflow), so support for any of your questions are never far away :)
API Docs and sample app
API docs: http://www.typhoonframework.org/docs/latest/api/
We have a nice sample app: https://github.com/jasperblues/Typhoon-example
Quality Control:
We also maintain a robust quality control system.
Every commit triggers a series of regression tests
We maintain high test coverage.
You don't have to instantiate the object in the NIB file. If you set the File's Owner to your object's class and then link things in the view/window/whatever up to that, you can set your object as the owner at runtime by loading the nib file manually. That way you can have a dynamic instance of an object that still gets dependencies injected properly.
What about dependecy injection implementation at Objective-IOC
What about ObjectivePim?
ObjectivePim
I’ve written a very simple DI container, the code is on GitHub. It can only do the bare basics, ie. discover the dependencies of an object and satisfy them using other given objects. I have found that to be usable in real-world applications, the code is very simple and it’s fun to hack with.
Has any looked at the Associative References feature of Mac OS X 10.6?
I believe with this it would be possible to build or already have something similar to DI.
As far as I have seen however any reference that is needed in an object has to be fetched manually using objc_getAssociatedObject().
Manfred
Interface Builder does not do ANY dependency injection. It does not need to. Interface Builder serializes objects. When a nib is "awoken" (aka opened), there are no "dependencies" to resolve -- there are just properties to set. Very, very simple. Opening a nib relies solely on the NSCoding protocol and key-value coding.
Dependency injection, pretty much a make-work project at the best of times, or at best a generalized glue layer between components designed independently, is of no use in well written Objective-C code. You are asking for a tool that you don't need.
In Objective-C, software that requires an anonymous service declares a Protocol. Services then adopt this protocol. Clients load services as dynamic plug-ins. On the other hand, if the server was written prior to the client, it is simply a matter of writing a new plug-in which adapts the existing interface to the protocol. This is less work, and more straightforward than trying to define an intermediate data-driven system for "discovering" (please) an interface at runtime.
Is it not obvious to everyone that the big secret of DI is just that it's a way to write code in XML instead of in the native language? I'd really like to hear a good argument as to how XML is somehow a better programming language than a real programming language. It doesn't make any sense.
I work with Spring all day and I've checked Groovy. I'm by no means an XCode/Cocoa expert, but IB does only some dependency injection, which Groovy doesn't even really claims to be doing.
I reckon you are not looking for DI, but rather for a well compiled set of integrated libraries which saves you from typing a lot of code which other people also have typed. I think there are no Spring like frameworks for Cocoa because for some reason people tend to see "Open Source" as "not platform dependant" and therefore Cocoa is a bit left out in the cold.
Depending on your needs though, there are some nice free open source libraries available for Cocoa, all listed on CocoaDev in a nice list.
I know it isn't Spring, but I hope it helps.
DI is a property of a runtime execution enviroment requiring dynamic binding. I'm very new to Obj-C and Cocoa so I may speak out of turn. Unless I'm missing something, I don't see how one could implement DI except by interpreting Obj C rather than compiling it, or by modifying the runtime environment.
I suspect that the DI like behaviour of IB is because there is a domain specific runtime environment associated with apps that are built with it.
I'm happy to be corrected though.
Categories appear to be an implementation of mixin's, allowing dynamic dispatch of methods to a delegate. Rather cool and similar to Java's interface concept, thought the details differ and from the following, I can't see if constants can be defined in a category, though member fields cannot.
objective-c categories
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Background:
I am taking a class at my university called "Software Constraints". In the first lectures we were learning how to build good APIs.
A good example we got of a really bad API function is the socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); in C#. The function receives 3 lists of sockets, and destroys them making the user have to clone all the sockets before feeding them into the Select(). It also has a timeout (in microseconds) which is an int, that sets the maximum time the server can wait for a socket. The limits of this is +/-35 minutes (because it is an int).
Questions:
How do you define an API as
'bad'?
How do you define an
API as 'good'?
Points to consider:
Function names that are hard to remember.
Function parameters that are hard to understand.
Bad documentation.
Everything being so interconnected that if you need to change 1 line of code you will actually need to change hundreds of lines in other places.
Functions that destroy their arguments.
Bad scalability due to "hidden" complexity.
It's required from the user/dev to build wrappers around the API so that it can be used.
In API design I've always found this keynote very helpful:
How to Design a Good API and Why it Matters - by Joshua Bloch
Here's an excerpt, I'd recommend reading the whole thing / watching the video.
II. General Principles
API Should Do One Thing and Do it Well
API Should Be As Small As Possible But No Smaller
Implementation Should Not Impact API
Minimize Accessibility of Everything
Names Matter–API is a Little Language
Documentation Matters
Document Religiously
Consider Performance Consequences of API Design Decisions
Effects of API Design Decisions on Performance are Real and Permanent
API Must Coexist Peacefully with Platform
III. Class Design
Minimize Mutability
Subclass Only Where it Makes Sense
Design and Document for Inheritance or Else Prohibit it
IV. Method Design
Don't Make the Client Do Anything the Module Could Do
Don't Violate the Principle of Least Astonishment
Fail Fast - Report Errors as Soon as Possible After They Occur
Provide Programmatic Access to All Data Available in String Form
Overload With Care
Use Appropriate Parameter and Return Types
Use Consistent Parameter Ordering Across Methods
Avoid Long Parameter Lists
Avoid Return Values that Demand Exceptional Processing
You don't have to read the documentation to use it correctly.
The sign of an awesome API.
Many coding standards and longer documents and even books (Framework Design Guidelines) have been written on this topic, but much of this only helps at a fairly low level.
There is also a matter of taste. APIs may obey every rule in whatever rulebook, and still suck, due to slavish adherence to various in-vogue ideologies. A recent culprit is pattern-orientation, wherein Singleton Patterns (little more than initialized global variables) and Factory Patterns (a way of parameterizing construction, but often implemented when not needed) are overused. Lately, it's more likely that Inversion of Control (IoC) and associated explosion in the number of tiny interface types that adds redundant conceptual complexity to designs.
The best tutors for taste are imitation (reading lots of code and APIs, finding out what works and doesn't work), experience (making mistakes and learning from it) and thinking (don't just do what's fashionable for its own sake, think before you act).
Useful - it addresses a need that is not already met (or improves on existing ones)
Easy to explain - the basic understanding of what it does should be simple to grasp
Follows some object model of some problem domain or real-world. It uses constructs that make sense
Correct use of synchronous and asynchronous calls. (don't block for things that take time)
Good default behavior - where possible allow extensibility and tweaking, but provide defaults for all that is necessary for simple cases
Sample uses and working sample applications. This is probably most important of all.
Excellent documentation
Eat your own dog food (if applicable)
Keep it small or segment it so that it is not one huge polluted space. Keep functionality sets distinct and isolated with few if any dependencies.
There are more, but that is a good start
A good API has a semantic model close to the thing it describes.
For example, an API for creating and manipulating Excel spreadsheets would have classes like Workbook, Sheet, and Cell, with methods like Cell.SetValue(text) and Workbook.listSheets().
A good API allows the client to do pretty much everything they need to do, but doesn't require them to do a lot of mindless busy-work. Examples of "mindless busy work" would be initializing data structure fields, calling several routines in a sequence that never varies with no real custom code in between, etc.
The surest sign of a bad API is if your clients all want to wrap it with their own helper code. At the absolute least, your API should have provided that helper code. Most likely, it should have been designed to provide the higher level of abstraction the clients are rolling themselves on their own every time.
A bad API is one that is not used by its intended audience.
A good API is one that is used by its intended audience for the purpose for which it was designed.
A great API is one that is used by both its intended audience, for the its intended purpose, and an unintended audience for reasons unanticipated by its designers.
If Amazon publishes its API as both SOAP and REST, and the REST version wins out, that doesn't mean the underlying SOAP API was bad.
I'd imagine that the same will be true for you. You can read all you want about design and try your best, but the acid test will be use. Spend some time building in ways to get feedback on what works and what doesn't and be prepared to refactor as needed to make it better.
A good API is one that makes simple things simple (minimum boilerplate and learning curve to do the most common things) and complicated things possible (maximum flexibility, as few assumptions as possible). A mediocre API is one that does one of these well (either insanely simple but only if you're trying to do really basic stuff, or insanely powerful, but with a really steep learning curve, etc). A horrible API is one that does neither of these well.
There are several other good answers on this already, so I thought I'd just throw in some links I didn't see mentioned.
Articles
"A Little Manual Of API Design" by Jasmin Blanchette of Trolltech
"Defining QT-Style C++ APIs" also Trolltech
Books:
"Effective Java" by Joshua Bloch
"The Practice Of Programming" by Kernighan and Pike
I think a good API should allow custom IO and memory management hooks if it's applicable.
A typical example is you have your custom compressed archive format for data on disk and a third party library with a poor api wants to access data on disk and expects a path to a file where it can load its data.
This link has some good points:
http://gamearchitect.net/2008/09/19/good-middleware/
If the API produces an error message, ensure that the message and diagnostics help a developer work out what the problem is.
My expectation is that the caller of an API passes in input that is correct. A developer is the consumer of any error messages produced by the API (not the end user), and messages aimed at the developer help the developer debug their calling program.
An API is bad when it is badly documented.
An API is good when it is well documented and follows a coding standard.
Now these are two, very simple and also very hard points to follow, this brings one into the area of software architecture. You need a good architect that structures the system and helps the framework follow its own guidlines.
Commenting code, writing an well explained manual for the API is Mandatory.
An API can be good if it has a good documentation which explains how to use it. But if the code is clean, good and follows a standard inside itself, it doesnt matter if it doenst have a decent documentation.
I've written a little about coding structure here
I think what is paramount is readability, by which I mean the quality that makes the greatest number of programmers to make sense of what the code is doing in the shortest possible amount of time. But judging which piece of software is readable and which is not has that indescribable human quality: fuzziness. The points you mention do partly succeed in crystallizing it. However, in its entirety it has to remain a case-by-case affair and it would be really hard to come up with universal rules.