API design: Flexibility Vs. Ease-of-use?

If you are part of a standards body that can enforce usage of your classes on others then you can go with flexible and complicated (e.g. Stl) For everyone else, unless there are some really compelling reasons, then ease of use should always be your first choice. Otherwise, few people will use your code/API. If the learning curve to use someone else's code is high then most people will opt to reimplement just the parts they need.

That is usually way quicker and problems are easier to resolve In my opinion, "ease of understandability" is 2nd only to "It Works Correctly" when it comes to rating the quality of code So bottom line, if adding flexibility comes at expense of easy to learn and use then don't add the flexibility until it is PROVEN that the flexibility is necessary.

If you are part of a standards body that can enforce usage of your classes on others then you can go with flexible and complicated (e.g. Stl). For everyone else, unless there are some really compelling reasons, then ease of use should always be your first choice. Otherwise, few people will use your code/API.

If the learning curve to use someone else's code is high then most people will opt to reimplement just the parts they need. That is usually way quicker and problems are easier to resolve.In my opinion, "ease of understandability" is 2nd only to "It Works Correctly" when it comes to rating the quality of code. So bottom line, if adding flexibility comes at expense of easy to learn and use then don't add the flexibility until it is PROVEN that the flexibility is necessary.

I think you need to consider the target audience for the library - if you're writing a library that less experienced developers may well use, you have to give thought to how to help them. In the case of the C++ STL probably most developers that are using them do not mind the extra mechanics because they are used to them and value the flexibility much more. You may want to think about two tiers of access through your API, that has a level that keeps things simple and a layer that allows for more control.

But you may want to see how the framework develops first before you go to that length.

I'm fond of the . NET base class library API. The design of the library most follows these guidelines.

While reading these, and the accompanying book, I took several key pieces of knowledge: The API was designed keeping in mind that modern editors have intellisense capabilities. Longer names are acceptable because you can tab-line complete class and method names. This is in opposition to C-style functions with shorter, obfuscated names like strnicmp() Use of the Create, Set, Call pattern: Always have a default, no parameter constructor.

Provide properties which can be set in any order, and then allow methods to be called. Using this pattern allows an object to be in an invalid state for a short period of time. (After the constructor was called, but before any properties were set) But this is okay.

You can communicate API misuse by throwing exceptions. This makes using the class more approachable.

This is certainly a subjective thing, though: I find the . NET APIs horrid. I prefer a functional-style APIs with mostly immutable types and free (or static) functions that operate on them.

Less state = reduced coupling, fewer threading issues, easier-to-read code. But this is a matter of opinion. – Robert Fraser Apr 30 '10 at 17:31.

I cant really gove you an answer,but what I can give you is a way to a solution, that is you have to find the anglde that you relate to or peaks your interest. A good paper is one that people get drawn into because it reaches them ln some way.As for me WW11 to me, I think of the holocaust and the effect it had on the survivors, their families and those who stood by and did nothing until it was too late.