Java API Design Checklist

Turn from:

Bole Online Java API Design Checklist

English original Theamiableapi

There are always a lot of different specifications and considerations when designing Java Apis. As with any complex thing, this work is often a test of the seriousness of our thinking. Just like the Pilot's checklist before takeoff, this checklist will help software designers recall clear or ambiguous specifications as they design the Java api. This article can also be seen as an addendum to the "API design guide" article.

We have also prepared some examples of how this list can help you clarify your design needs, identify errors, identify bad design practices, and find opportunities for Improvement.

This checklist uses the following language specification:

To – represent the necessary design

Recommendations – Indicates the choice of a few of the best designs

Consider – represents a possible design improvement

Avoidance – Represents a design flaw

No – Indicates a design error

1. Package Design Checklist 1.1. Common

▲1.1.1. It is recommended to put the API and implementation into different packages

▲1.1.2. It is recommended to put the API in the upper package, and put the implementation into the lower package

▲1.1.3. Strong> Consider splitting a large set of APIs into different packages

▲1.1.4. Consider packaging the API and implementation into different jar packages

▲1.1.5. Avoiding internal dependencies between the implementation classes of the API

▲1.1.6. Avoid splitting the API too thin

▲1.1.7. Avoid putting public implementation classes into packages in the API

▲1.1.8. do not establish dependencies between the caller and the implementation class

▲1.1.9. do not put the Non-relational API into the same package

▲1.1.10. do not put the API and SPI (service provider Interface) into a package (note: this page can be viewed differently http://stackoverflow.com/questions/2954372 /difference-between-spi-and-api)

▲1.1.11. do not move or rename a public API that has been published

1.2. naming

▲1.2.1. (first-level) The package name is named after the company (or Organization) 's root namespace

▲1.2.2. use a stable product name or a product family name as the Two-level name of the package

▲1.2.3. using the API name as the package name (level three Name) end

▲1.2.4. consider including the word "internal" in the name of the package that contains only the implementation (note: "impl" appears to be more Common)

▲1.2.5. Avoiding the use of combined names

▲1.2.6. avoid using the same name for the package name and the class name within the package

▲1.2.7. Avoid using the word "api" in the package name

▲1.2.8. do not use marketing, planning, organizational units (departments), and Geographic Names

▲1.2.9. do not use uppercase letters in the package name

1.3. Documentation

▲1.3.1. provide a package.html for each package

▲1.3.2. compliance with standard Javadoc

▲1.3.3. summarize (describe) In a short sentence at the beginning of the API

▲1.3.4. provide enough detail to help you determine if you need to use and how to use the API

▲1.3.5. indicate the ingress of the API (primary class or METHOD)

▲1.3.6. contains sample code that covers the main, basic function demo

▲1.3.7. include a hyperlink to the developer guide

▲1.3.8. contains a hyperlink to a manual

▲1.3.9. indicates the associated API collection

▲1.3.10. The version number that contains the API

▲1.3.11. Marking API versions that are no longer used with @deprecated

▲1.3.12. Consider adding a copyright notice

▲1.3.13. Avoid too long package overview

▲1.3.14. do not include implementation-related packages in the published Javadoc

2. Type Design Checklist

(here the "type" of the individual is understood as a set of Apis)

2.1. Common

▲2.1.1. ensure that each type of (design) has a single, clear purpose

▲2.1.2. Ensure that each type represents the concept of the (business) domain, not for (technically) abstract

▲2.1.3. Total number of restriction types

▲2.1.4. Limiting the size of a type

▲2.1.5. Maintaining consistency with the original type when designing related types

▲2.1.6. It is recommended to provide multiple (private) implementations for various types of public

▲2.1.7. classes that implement classes and inheritance relationships that suggest interfaces should be consistent in their behavior

▲2.1.8. It is recommended to use an abstract class rather than an interface to decouple the implementation of the API

▲2.1.9. It is recommended to use enumerations instead of constants

▲2.1.10. consider using generics

▲2.1.11. consider adding constraints on generic parameters

▲2.1.12. Consider the use of interfaces to achieve multiple inheritance effects

▲2.1.13. Avoid designing for users ' extensions (requirements)

▲2.1.14. Avoiding depth of inheritance hierarchy

▲2.1.15. do not use public-embedded types

▲2.1.16. do not declare variables for public and protected

▲2.1.17. do not expose the inherited relationship to the user

2.2. naming

▲2.2.1. using nouns or noun phrases

▲2.2.2. use of pascalcasing (name of the Hump for more details Http://en.wikipedia.org/wiki/CamelCase)

▲2.2.3. Initials only the first initial letter of capitalization

▲2.2.4. use precise name naming for the actual role of the type

▲2.2.5. preparing the shortest and easiest- to-remember names for the most commonly used types

▲2.2.6. All exceptions end with "Exception"

▲2.2.7. Use the singular of a noun (for example, with color instead of Colors) to name the enumeration type

▲2.2.8. Consider a longer name

▲2.2.9. consider that derived classes end with the name of the base class

▲2.2.10. consider starting with "abstract" for abstract class names

▲2.2.11. Avoid using acronyms

▲2.2.12. avoid too generic nouns

▲2.2.13. Avoiding Synonyms

▲2.2.14. Avoid using the name of the type in the associated API

▲2.2.15. do not use names that differ only in case

▲2.2.16. do not use prefixes

▲2.2.17. do not start with the name "I" as the interface

▲2.2.18. do not (repeat) use the name in the Java core package

2.3. class

▲2.3.1. minimizing dependencies used by implementations

▲2.3.2. Listing public methods first

▲2.3.3. affirm that the implementation method is private (is this a clerical error?) )

▲2.3.4. defining at least one public for a public abstract class Shi

▲2.3.5. provide sufficient default implementations for basic usage

▲2.3.6. design of essentially immutable classes

▲2.3.7. to assemble a stateless, accessor, extension (a method that Mutator personally understood as a variety of parameter Forms)

▲2.3.8. Control the number of extension methods to a minimum

▲2.3.9. Consider designing a default, non-parametric construction method

▲2.3.10. Consider overriding the Equal,hashcode method

▲2.3.11. Consider implementing the comparable interface

▲2.3.12. Consider implementing the Serializable interface

▲2.3.13. Consider making classes easy to extend

▲2.3.14. Consider the Declaration class as final

▲2.3.15. Consider providing a public constructor for the instantiation of a class

▲2.3.16. Consider using custom types to enhance the immutability of classes

▲2.3.17. Considering design immutable classes

▲2.3.18. Avoiding static classes

▲2.3.19. Avoid using cloneable

▲2.3.20. do not add an instance to a static class Duixi

▲2.3.21. do not provide public-constructed methods for public abstract classes that the consumer should not extend

▲2.3.22. do not misuse initialization

2.4. Interface

▲2.4.1. provide at least one implementation class for each public interface

▲2.4.2. Design At least one consumption method for each public interface

▲2.4.3. do not add a new method to a public interface that has been published

▲2.4.4. do not use tag interfaces (see Http://en.wikipedia.org/wiki/Marker_interface_pattern for marking interfaces)

▲2.4.5. do not design the public interface as a constant container (this is very common ...). )

2.5. Enumeration

▲2.5.1. Consider specifying a 0 value for the enumeration type ("NONE" or "unspecialized", etc.)

▲2.5.2. Avoiding enumerations with only one value

▲2.5.3. do not use enumerations to implement an open set of values

▲2.5.4. do not design enumerations for values that may be added in the future

▲2.5.5. do not add new enumeration values for published versions

2.6. Exceptions

▲2.6.1. Ensure that custom exceptions can be serialized

▲2.6.2. Consider defining a different exception for each type

▲2.6.3. Consider providing more exception information for code access

▲2.6.4. Avoiding deep exception inheritance

▲2.6.5. do not derive a custom exception from a class other than exception and RuntimeException

▲2.6.6. do not derive exceptions directly from Throwable

▲2.6.7. do not include sensitive information within the exception message

2.7. Documentation

▲2.7.1. for each type (api) with an overview

▲2.7.2. following the conventions of standard Javadoc

▲2.7.3. The beginning of each type is outlined in a short sentence

▲2.7.4. provide enough detail for use and how to use the type to help make a decision

▲2.7.5. explanation of how to instantiate a type

▲2.7.6. providing sample code for a type of primary usage scenario

▲2.7.7. include a link to the development guide

▲2.7.8. include links to manuals

▲2.7.9. Display related types

▲2.7.10. declaring obsolete types with @deprecated tags

▲2.7.11. document classes have immutability

▲2.7.12. Avoiding lengthy classes overview

▲2.7.13. do not generate Javadoc for private methods

3. Method Design Checklist 3.1. Common

▲3.1.1. ensure that each method achieves one purpose

▲3.1.2. Ensure that the relevant methods are of a granular level

▲3.1.3. Ensure that there is no common code for mixed call methods

▲3.1.4. making calls to all methods atomic (atomic: http://jiangyongyuan.iteye.com/blog/364010)

▲3.1.5. Design The protected method as carefully as the public method

▲3.1.6. Limiting the number of extension methods

▲3.1.7. The design extension method needs to have the strong stability

▲3.1.8. It is recommended to design a generic method for a series of overloaded methods

▲3.1.9. Consider using generic methods

▲3.1.10. Considering the design method, the effect of two methods is the opposite .

▲3.1.11. Avoid "helper" methods

▲3.1.12. ways to avoid long-time execution

▲3.1.13. prevent callers from requiring manual write loops in normal use

▲3.1.14. Avoiding the behavior of optional parameters affecting methods

▲3.1.15. ways to avoid non-repeatable calls

▲3.1.16. do not delete a method that has been published

▲3.1.17. do not mark an already published method as obsolete before you provide a replacement method

▲3.1.18. do not modify the signature of an already published method

▲3.1.19. do not modify the observable behavior of an already published method (perhaps referring to output, etc.)

▲3.1.20. do not add a call condition for a method that has been published

▲3.1.21. do not reduce the call result of a method that has been published

▲3.1.22. do not add a new method to the public interface that has been published

▲3.1.23. do not add an overload for an API that has already been published

3.2. naming

▲3.2.1. a verb with a force, as the beginning of a name

▲3.2.2. using the Hump naming method (very strange, The front is written Pascalnaming)

▲3.2.3. to reserve access methods such as "get" "set" "is" for the private properties of JavaBean

▲3.2.4. using words that are familiar to callers

▲3.2.5. use spoken English as much as possible

▲3.2.6. Avoid using acronyms

▲3.2.7. Avoid the use of general verbs

▲3.2.8. Avoiding Synonyms

▲3.2.9. do not use "slang"

▲3.2.10. do not rely on the name and type of the parameter to determine the meaning of the method

3.3. Parameters

▲3.3.1. Choosing the most appropriate type for a parameter

▲3.3.2. maintaining consistency in the handling of null values for parameters in calls to related methods

▲3.3.3. the name, type, and order of the parameters in the related method need to be consistent

▲3.3.4. placing the output parameters in the parameter list after the input parameters

▲3.3.5. omit common default parameters for overloaded methods to provide a shorter argument list

▲3.3.6. providing overloaded methods for operations of the same semantics in unrelated types

▲3.3.7. It is recommended to use interfaces instead of specific classes as parameters

▲3.3.8. It is recommended that you use collections instead of arrays as parameters and return values

▲3.3.9. It is recommended to use a generic collection instead of the original (no Type) collection

▲3.3.10. It is recommended to use enumerations instead of Boolean or integer as arguments

▲3.3.11. It is recommended to put a single parameter before the set or array parameter

▲3.3.12. It is recommended to enlarge the parameters of the custom type before the Java standard type parameter

▲3.3.13. the argument of the object type is recommended before the parameter method value type

▲3.3.14. It is recommended to use an interface instead of a specific class as the return value

▲3.3.15. It is recommended to put an empty collection instead of NULL as the return value

▲3.3.16. It is recommended to design the return value as a valid input parameter that can be used as another method

▲3.3.17. Consider designing a replica for immutable parameters

▲3.3.18. Consider storing weakly referenced objects internally

▲3.3.19. Avoid changing the number of parameters

▲3.3.20. Avoid too long parameter lengths (more than 3)

▲3.3.21. Avoid continuous parameters of the same type

▲3.3.22. Avoid parameters used as output or input and output

▲3.3.23. Avoiding method overloading

▲3.3.24. Avoiding parameter types exposing implementation details

▲3.3.25. Avoiding the Boolean parameter

▲3.3.26. Avoid returning null

▲3.3.27. In addition to the Java core api, avoid the return value of the type as an irrelevant API

▲3.3.28. Avoid referencing variable internal objects as return values

▲3.3.29. do not use pre-set constants As Integer value parameters

▲3.3.30. do not consider reservation parameters for future (extended Design)

▲3.3.31. do not change the order of the names of parameters in overloaded methods

3.4. Exception Handling

▲3.4.1. exceptions are thrown only in exceptional cases

▲3.4.2. Just throw a confirmed exception for a recoverable error

▲3.4.3. throwing a Run-time exception in order to notify the API of using errors

▲3.4.4. throwing exceptions at the appropriate level of abstraction

▲3.4.5. checking for run-time preset conditions

▲3.4.6. throwing a null pointer exception for a parameter that cannot be null

▲3.4.7. Exclude Illegal parameter exceptions for a parameter other than NULL for an exception value

▲3.4.8. throwing an illegal state exception for a method call in an error context

▲3.4.9. the preset condition of the parameter is displayed in the error message

▲3.4.10. Ensure that failed method calls have no one-way consequences

▲3.4.11. providing Run-time checks for prohibited APIs in callback methods

▲3.4.12. Java Standard Exceptions recommended for priority use

▲3.4.13. query methods that provide conditions for throwing exceptions

3.5. rewrite

▲3.5.1. using @Override annotations

▲3.5.2. to maintain or weaken a preset condition

▲3.5.3. maintain or strengthen the post conditions (not good translation, probably output+effect Meaning)

▲3.5.4. maintaining or strengthening immutability

▲3.5.5. do not throw new Run-time exceptions

▲3.5.6. do not change the type of method (stateless, accessor or extension method, etc.)

3.6. Construction Method

▲3.6.1. work in the minimized construction method

▲3.6.2. Set reasonable default values for all properties

▲3.6.3. a quick way to set parameters only as a parameter of a construction method

▲3.6.4. verifying The parameters of the construction method

▲3.6.5. Name the corresponding property of the parameter

▲3.6.6. When multiple construction methods are provided, follow the guidelines to overload them

▲3.6.7. It is recommended to use a construction method instead of a static factory method

▲3.6.8. Consider using an Argument-free construction method

▲3.6.9. If you don't always need a new instance, consider using a static factory method

▲3.6.10. If you need to decide on a suitable type at run time, consider using a static factory method

▲3.6.11. If you need to access external resources, consider using a static factory method

▲3.6.12. when faced with a very high number of parameters, consider using the generator (builder)

▲3.6.13. use a private constructor when you need to avoid a direct instantiation of a class

▲3.6.14. Avoid creating non-essential objects

▲3.6.15. Avoiding Finalizer

▲3.6.16. do not throw exceptions from an Argument-free construction method

▲3.6.17. do not add a display construction method to a class that has already been published

3.7. Setters and getters

▲3.7.1. A method that names a return value that is not a Boolean access property, starting with Get

▲3.7.2. a method that names an access property that returns a Boolean value starting with Is,can

▲3.7.3. naming a method that updates local variables at the beginning of a set

▲3.7.4. Verifying the parameters of the setter method

▲3.7.5. work to minimize getter and setter methods

▲3.7.6. Consider returning an immutable collection from a getter method

▲3.7.7. Consider implementing a collection of private interfaces instead of the collection property of public

▲3.7.8. consider read-only properties

▲3.7.9. Consider defensive copy when setting the properties of a mutable type (defensive copy see : http://www.javapractices.com/topic/ Topicaction.doid=15)

▲3.7.10. Consider defensive Copy when returning properties of a mutable type

▲3.7.11. getter Method avoids returning an array

▲3.7.12. Avoid checks that cannot be completed based on the information in the method

▲3.7.13. do not throw exceptions from getter methods

▲3.7.14. do not design property methods that can only be set (public setters only and getter with no Public)

▲3.7.15. do not rely on the order of property settings

3.8. Callbacks

▲3.8.1. design with the most stringent preset conditions

▲3.8.2. using the weakest post condition at design time

▲3.8.3. Consider passing the callback interface as the first parameter in a method that takes a reference object

▲3.8.4. to avoid callback methods with return values

3.9. Documentation

▲3.9.1. providing Javadoc annotations for each method

▲3.9.2. compliance with standard Javadoc conventions

▲3.9.3. Each method is outlined in a short sentence

▲3.9.4. Declaration of relevant methods

▲3.9.5. declaring obsolete types with @deprecated tags

▲3.9.6. Show alternate methods for all obsolete methods

▲3.9.7. Avoid lengthy Zhus

▲3.9.8. include common usage patterns

▲3.9.9. (if allowed) contains the exact meaning of a null value

▲3.9.10. The type of the containing method (stateless, accessor, or Extension)

▲3.9.11. Preset conditions that contain methods

▲3.9.12. performance characteristics that include algorithm implementations

▲3.9.13. include remote method calls

▲3.9.14. include methods to access external resources

▲3.9.15. What APIs are included that can be used in callbacks

▲3.9.16. consider including unit tests in order to describe the behavior of the method

(go) Java API Design Checklist