| 失效链接处理 |
|
Java API Best Practices PDF 下载
本站整理下载：
相关截图：
主要内容：
3. CONSISTENT
A good API should not surprise its users, and one way we can fail
at this is by not being consistent. When we speak of consistency,
we mean ensuring that we repeat the same concepts in our API,
rather than introduce different concepts in an adhoc fashion.
Examples include:
• All of our methods should have the form getXYZ() or
xyz(), but not both forms.
• If there are two methods (one a convenience overload of
the other, e.g. one taking Object... (that is, a var-args of
Object) and the other taking Collection<? extends
Object>), that overload should be available everywhere.
The point here is to establish a team-wide vocabulary and "cheat
sheet" that we use to apply a veneer of consistency across our
entire SDK.
4. FIT FOR PURPOSE
In developing an API, we must ensure that we target it at the right
level for the intended user. This can be thought of in two ways:
1. Do only one thing, and do it right.
2. Understand your user and their goals.
A good example is the Collections APIs included with the JDK. The
user should be able to store and retrieve items from a collection
very easily, without first defining a reallocation threshold,
configuring a factory, specifying a growth policy, a hash collision
policy, a comparison policy, a load factor, a caching policy, and
so on. Developers should never be expected to know the inner
working of a collections framework to benefit from its functionality.
5. RESTRAINED
Creating a new API can happen almost too quickly, but we should
remember that for every new API, we are potentially committing
to a lifetime of support.
The actual cost of our API decisions depends a lot on our project
and its community — some projects are happy to make breaking
changes constantly, whereas others (such as the JDK itself) are
eager to break as little as possible. Most projects fall in the middle
ground, adopting a semantic versioning approach that carefully
deprecates an API before removing it only in major releases.
Some projects even go so far as to include various markers to
indicate experimental, beta, or preview functionality that makes
it available in releases for feedback before a final API is locked
down. A common approach is to introduce this new, experimental
functionality with the @Deprecated annotation, and to then
remove the annotation when the API is considered ready.
6. EVOLVABLE
For every API decision we make, we are potentially backing
ourselves into another corner. As we make API decisions, we must
take the time to view them in the wider context of the future
releases of the SDK.
API AS A CONTRACT
API has to be thought of as a contract — when we make an API
available to other developers, we are promising them a certain
functionality. It is often hard for engineers to leave their code
alone, as they constantly imagine new and better approaches
(even when not working). Thinking that we should revise our
API, to attempt to make it better, should only be done after much
consideration, as we risk introducing breaking changes and bugs
to the developers downstream from us.
In the build up to the 1.0.0 release of our API, we should feel a
sense of freedom to experiment. In some projects, the point at
which we reach 1.0.0 is the point in which our API becomes locked
down (at least until the 2.0.0 release). However, in other projects,
there can be more flexibility with their obligations, continuing to
experiment and refine their API on an ongoing basis. In fact, with
a wise deprecation process, it is not too hard to evolve an API in
a backwards-compatible way over a long period of time, without
restricting the ability to introduce better approaches.
THE IMPORTANCE OF JUSTIFICATION
The easiest API to maintain is no API at all, and it is therefore
extremely important to require justification for every method and
class that forms part of our API. During the process of designing
our APIs, we should frequently find ourselves asking the following
question: "Is this really required?" We should assure ourselves
that the API is paying for itself, returning vital functionality in
return for its continued existence.
EATING YOUR OWN DOGFOOD
As API developers we have to be careful that the API we are
creating is indeed useful for its stated purpose. We have to have
developer empathy to look through the eyes of the developer,
rather than as ourselves. The best way to be assured of this is
to "eat your own dog food." In other words, it is important to
ensure that the API is used throughout its development, not only
by yourself, but also — and more importantly — by trusted "real
world" users.
The value of bringing in "real world" users is to help prevent
ourselves from losing our sense of restraint, and adding
enhancements based solely on our advanced understanding of
|
| Java1234官方群25： | 
|
| Java1234官方群25： | 838462530 |
苏公网安备 32061202001004号
