What is better? some advices about designing a goode API

There are some good articles that introduced the API designing. I read them and collected them here: In my definition, good code must embody qualities like the following:

• It is easy to maintain
• It is easy to reuse in other contexts
• It has minimal external dependencies
• It is adaptable to new problems
• Its behavior is safe and predictable

This list can be further distilled into the following three categories

• It must be refactorable
• It must be extensible
• It must be written defensively

Methodology of designing API
You should carry out the top down design, coz the beneifits is the following:

• you get solid API design early on.
• you are assured that all the components will fit together.This often makes for less reengineering than needed in the bottom-up model.

Writing code that is easy to refactor is central to having reusable and maintainable code. So how do you design code to be easily refactored? These are some of the Key:

• Encapsulating Logic in function: A key way to increase code reusability and manageability is to compartmentlize the logic in function. The tiny bit of a logic into a function.
• Keeping Classes and Function Simple : An individual function or method should perform a single simple task. Simple functions are then used by other functions. which is how complex tasks are completed. This methodology is preferred over writing monolithic fuctions because it promoteds reuse.
• Namespacing : This is absolutely critical in any large code base. Using namespacing provides the following benefits: 1) It encourages descriptive naming of functions. 2) It provides a way to find the physical location of a function based on its name. 3)It helps avoid naming confilicts. You can autherticate many things: site members, administrative users. and credit cards, for instance. member_authenticate(), admin_user_authenticate(), and creditCard_authenticate() make it clear what you mean.
• reducing coupling : Coupling occors when one function, class, or code entity depends on another to function correctly. You need to be conscious of the causality: Stable code is not nessarily highly coup0led. but highly coupled code must be stable. If you have classed that you know will be core or foundation classes. make sure you invest time in getting their APIs right early, before you have so much code referencing them that a redesign is impossible. further reading: Say no when facing coupling
• Defensive Coding : This is the practice of eliminating assumptions in the code. especially when it comes to handing information in and out other routines. there aer tow keys to effective defensive coding in PHP: 1) Establishing coding standards to prevent accidental sytax bugs. 2) Using sanitization techniques to avoid malicious date. further reading: wiki: defensive programming
• Establishing Standard Conventions : The easy way to make sure other developers use your code correctly is to make sure that all your dode follows standards for argument order and returens। Return values should be similarly well defined and consistent. For Boolean functions , this is simple: Return true on success and false on failure.

Design Practices
 These are some practices came form the website newbeans.org that help the writer and maintainer to achieve the general suggestions and rules.
Do not expose more than you want
Obviously the less of the implementation is expressed in the API, the more flexiblility one can have in future. there are some tricks that one can use to hide the implementation, but still deliver the desired functionality. they are the following:

• Method is better than field: It is better to use methods(usually getters and setters) to access fields than to expose them directly. The first of reason is that a call to a method can do a lot of additional things, but in contrast an access to a filed can only read or write the value.
• Factory is better than constructor: It is more flexible to expose a factory method than to expose constractor. the factory method is usually a static method that takes the same arguments as the constructor and return instace of the same class, but some subclass--allows to use polymorphism and possibley clean the code.
• Make everything final : If you are writing an API and you explicitly do not want people to subclass or implement your interfaces, it is better to disallow that. simplest solution is to make your class final. other tricks inclde non-public constructors(One shall do it anyway in favor of facotory methods) or making all method private.
• Allow access only from a friend code : It is a useful technique to not expose too much in API is to give access to certain functionality just to "friend" code.

Interface vs. abstract classes
The class are better for clent API and interfaces for service provider API, So, if your know that most of users of an API will just make calls to it. it is better to use classes (and the best thing is to make them unsubclassable, that way one prevents accidental subclasses at all). If you want people just to subclass, then choose interfaces, they are more safe and eay to used when subclassing.