Shulou(Shulou.com)06/02 Report--

Today I will show you what the design list of Java API is. The content of the article is good. Now I would like to share it with you. Friends who feel in need can understand it. I hope it will be helpful to you. Let's read it along with the editor's ideas.

There are always many different specifications and considerations when designing Java API. Like anything complicated, this work is often a test of how carefully we think. Like a pilot's pre-flight checklist, this list will help software designers recall explicit or ambiguous specifications in the process of designing a Java API.

We have also prepared some pre-and post-comparison examples to show how this list can help you sort out design requirements, identify errors, identify bad design practices, and find opportunities for improvement.

This list uses the following language specifications:

To-to indicate the necessary design

Suggestion-indicates that you choose one of the best designs

Consider-represents a possible design improvement

Avoid-indicate a design flaw

Don't-indicate a design error

1. Package design list

1.1. In common

1.1.1. It is recommended that you put API and implementation in different packages

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

1.1.3. Consider splitting a large set of API into different packages

1.1.4. Consider packaging API and implementation into different jar packages

1.1.5. Avoid internal dependencies between API implementation classes

1.1.6. Avoid breaking up API too fine.

1.1.7. Avoid putting public implementation classes in API packages

1.1.8. Do not establish a dependency between the caller and the implementation class

1.1.9. Don't put unrelated API in the same package.

1.1.10. Do not put API and SPI (service provider interface) in the same package (Note: if there is a difference between the two, please see this page http://stackoverflow.com/questions/2954372/difference-between-spi-and-api)

1.1.11. Do not move or rename a published public API

1.2. Naming

1.2.1. The package name is named after the root namespace of the company (or organization)

1.2.2. Use a stable product name or the name of a product family as the secondary name of the package

1.2.3. Use the API name as the end of the package name (tertiary name)

1.2.4. Consider including the word "internal" in the name of the package that contains only the implementation (note: it seems that "impl" is more common)

1.2.5. Avoid using combined names

1.2.6. Avoid using the same name as the class name in the package

1.2.7. Avoid using the word "api" in package names

1.2.8. Do not use marketing, planning, organizational units (departments) and geographic names

1.2.9. Do not use uppercase letters in package names

1.3. Document

1.3.1. Provide a package.html for each package

1.3.2. Follow the standard javadoc specification

1.3.3. Summarize (describe) in a short sentence at the beginning of the API

1.3.4. Provide enough details to help determine whether and how to use the API

1.3.5. Indicate the entry to the API (the main class or method)

1.3.6. Contains sample code that covers major, basic functional demonstrations

1.3.7. Contains a hyperlink to the developer's guide

1.3.8. Contains a hyperlink to the manual

1.3.9. Indicate the relevant API collection

1.3.10. Contains the version number of the API

1.3.11. Mark the API version that is no longer in use with @ deprecated

1.3.12. Consider adding a copyright notice

1.3.13. Avoid overly long package overview

1.3.14. Do not include implementation-related packages in the released javadoc

two。 Type design list (the "type" here is personally understood as a set of Api)

2.1. In common

2.1.1. Ensure that each type (designed) has a single clear purpose

2.1.2. Make sure that each type represents the concept of the domain, not for the purpose of abstraction

2.1.3. Limit the total number of types

2.1.4. Limit the size of a type

2.1.5. Maintain consistency with the original type when designing related types

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

2.1.7. It is recommended that the implementation classes of the interface and the classes of inheritance relationships should be consistent in behavior.

2.1.8. It is recommended that the implementation of Api be decoupled with abstract classes rather than interfaces

2.1.9. It is recommended that you use enumerations instead of constants

2.1.10. Consider using generics

2.1.11. Consider adding constraints to generic parameters

2.1.12. Consider using interfaces to achieve the effect of multi-inheritance

2.1.13. Avoid designing for user extensions (requirements)

2.1.14. Avoid deep 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 inheritance relationship of the implementation to the user

2.2. Naming

2.2.1. Use nouns or noun phrases

2.2.2. Use PascalCasing (for a nickname for hump nomenclature see http://en.wikipedia.org/wiki/CamelCase)

2.2.3. Abbreviations are only capitalized with the first initials.

2.2.4. Use a precise name for the actual role of the type

2.2.5. Prepare the shortest and most memorable names for the most commonly used types

2.2.6. All exceptions end with "Exception"

2.2.7. Use the singular of nouns (such as Color instead of Colors) to name enumerated types

2.2.8. Consider a longer name

2.2.9. Consider that the derived class ends 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 nouns that are too general

2.2.13. Avoid synonyms

2.2.14. Avoid using the name of the type in the related 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 "I" as the name of the interface

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

2.3. Class

2.3.1. Minimize dependencies used by the implementation

2.3.2. List the public method first

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

2.3.4. Define the shi of at least one public for an public abstract class

2.3.5. Provide sufficient default implementation for basic usage

2.3.6. Classes that are basically unchanged in design

2.3.7. Bring together stateless, accessor, extension (mutator personally understood as methods in the form of multiple parameters) methods

2.3.8. Keep the number of extension methods to a minimum

2.3.9. Consider designing a default no-parameter construction method

2.3.10. Consider rewriting 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 declaring the class as final

2.3.15. Consider providing a construction method of public for class instantiation

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

2.3.17. Consider designing immutable classes

2.3.18. Avoid static classes

2.3.19. Avoid using Cloneable

2.3.20. Do not add instance duixi to static classes

2.3.21. Do not provide public constructors for public abstract classes that consumers should not extend

2.3.22. Don't abuse 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 new methods to a published public interface

2.4.4. Do not use tagged interfaces (see http://en.wikipedia.org/wiki/Marker_interface_pattern for details of tagged interfaces)

2.4.5. Don't design the public interface as a constant container (this is really common. )

2.5. Enumerate

2.5.1. Consider specifying a value of 0 for enumerated types ("NONE" or "Unspecialized", etc.)

2.5.2. Avoid enumerations with only one value

2.5.3. Do not use enumerations to implement an open collection of values

2.5.4. Do not design enumerations for values that may increase in the future

2.5.5. Do not add new enumeration values to the released version

2.6. Abnormal

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. Avoid deep exception inheritance

2.6.5. Do not derive custom exceptions from classes other than Exception and RuntimeException

2.6.6. Do not derive exceptions directly from Throwable

2.6.7. Do not include sensitive information in abnormal information

2.7. Document

2.7.1. Provide an overview of each type (of Api)

2.7.2. Follow the convention of standard Javadoc

2.7.3. Each type begins with a short summary

2.7.4. Provide sufficient details for whether and how to use the type to help make a decision

2.7.5. Explain how to instantiate a type

2.7.6. Provide sample code for a type of primary usage scenario

2.7.7. Contains links to the development guide

2.7.8. Contains a link to the manual

2.7.9. Show related types

2.7.10. Declare obsolete types with the @ deprecated tag

2.7.11. Document classes are immutable

2.7.12. Avoid lengthy class overview

2.7.13. Do not generate Javadoc for private methods

3. Method design list

3.1. In common

3.1.1. Ensure that each method achieves a purpose

3.1.2. Ensure that the relevant methods are at the same level of granularity

3.1.3. Make sure there is no common code that mixes the calling method

3.1.4. Make all method calls atomic (atomicity: http://jiangyongyuan.iteye.com/blog/364010)

3.1.5. The protected method should be designed as carefully as the public method

3.1.6. Limit the number of extension methods

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

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

3.1.9. Consider using a generic approach

3.1.10. Consider that the effect of the design method is opposite to that of the two methods.

3.1.11. Avoid the "helper" method

3.1.12. Ways to avoid long execution

3.1.13. Avoid the need for callers to write loops manually in normal use

3.1.14. Avoid optional parameters that affect the behavior of the method

3.1.15. Avoid non-repeatable methods

3.1.16. Do not delete a published method

3.1.17. Do not mark a published method as obsolete without providing an alternative method

3.1.18. Do not modify the signature of a published method

3.1.19. Do not modify the observable behavior of a published method (perhaps referring to output or the like)

3.1.20. Do not add a condition for calling a published method

3.1.21. Do not reduce the result of a call to a published method

3.1.22. Do not add new methods to the published public interface

3.1.23. Do not add new overloads for Api that have been released

3.2. Naming

3.2.1. Use a powerful, expressive verb as the beginning of a name

3.2.2. Use the hump nomenclature (strangely, it says PascalNaming)

3.2.3. Set aside "get", "set", "is" and other access methods for private attributes of JavaBean

3.2.4. Use words that are familiar to the caller

3.2.5. Try to use spoken English

3.2.6. Avoid using acronyms

3.2.7. Avoid using general verbs

3.2.8. Avoid synonyms

3.2.9. Don't use "slang"

3.2.10. Don't rely on the name and type of parameters to judge the meaning of the method.

3.3. Parameters.

3.3.1. Select the most appropriate type for the parameter

3.3.2. Maintain consistency in the handling of null parameters in calls to related methods

3.3.3. The name, type and order of parameters need to be consistent in related methods.

3.3.4. Put the output parameter after the input parameter in the parameter list

3.3.5. Omit the commonly used default parameters for overloaded methods to provide a short list of parameters

3.3.6. Provide overloaded methods for operations with the same semantics in unrelated types

3.3.7. It is recommended that you use interfaces instead of concrete classes as parameters

3.3.8. It is recommended that you use a collection instead of an array as parameters and return values

3.3.9. It is recommended that you use a general collection instead of the original (untyped) collection

3.3.10. It is recommended that you use enumerations instead of Boolean or Integer as parameters

3.3.11. It is recommended that you put a single parameter in front of a collection or array parameter

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

3.3.13. It is recommended to set the parameters of the object type, the method, the value type, before the parameters of the type.

3.3.14. It is recommended to use the interface instead of the concrete class as the return value

3.3.15. It is recommended that you use an empty collection instead of null as the return value

3.3.16. It is suggested that the return value should be designed as a legal input parameter for other methods.

3.3.17. Consider designing a copy for immutable parameters

3.3.18. Consider storing objects with weak references internally

3.3.19. Avoid changing the number of parameters

3.3.20. Avoid too long parameter length (more than 3)

3.3.21. Avoid continuous parameters of the same type

3.3.22. Avoid parameters that are used as output or input and output

3.3.23. Avoid method overloading

3.3.24. Avoid parameter types exposing implementation details

3.3.25. Avoid boolean parameters

3.3.26. Avoid returning null

3.3.27. In addition to the Java core Api, avoid using types as return values for unrelated Api

3.3.28. Avoid referencing mutable internal objects as return values

3.3.29. Do not use preset constants as integer value parameters

3.3.30. Do not consider reserving 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. An exception is thrown only in an exception case

3.4.2. You only need to throw a confirmed exception for a recoverable error

3.4.3. To notify Api of a usage error, a runtime exception is thrown

3.4.4. Throw an exception at the appropriate level of abstraction

3.4.5. Check run-time preset conditions

3.4.6. Throws a null pointer exception for a parameter that cannot be null

3.4.7. Exclude illegal parameter exceptions for a parameter with an outlier other than null

3.4.8. Throw 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 do not have one-way consequences

3.4.11. Provides run-time checks for prohibited Api in callback methods

3.4.12. It is recommended to give priority to the use of Java standard exceptions

3.4.13. It is suggested to provide a query method for the conditions under which an exception is thrown

3.5. Rewrite

3.5.1. Use @ Override annotations

3.5.2. Maintain or weaken preset conditions

3.5.3. Maintain or strengthen the post-condition (difficult to translate, probably means output+effect)

3.5.4. Maintain or enhance immutability

3.5.5. Do not throw new runtime exceptions

3.5.6. Do not change the type of method (stateless, accessor, extension method, etc.)

3.6. Construction method

3.6.1. Minimize the work in the construction method

3.6.2. Set reasonable default values for all properties

3.6.3. Only use the parameters of the construction method as a quick way to set the parameters

3.6.4. Check the parameters of the construction method

3.6.5. Name the parameter after its corresponding attribute

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

3.6.7. It is recommended that you use a constructor instead of a static factory method

3.6.8. Consider using the construction method without parameters

3.6.9. If new instances are not always needed, consider using a static factory approach

3.6.10. If you need to decide on an appropriate 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. Consider using a generator (builder) when faced with a large number of parameters

3.6.13. Use a constructor that considers private when you need to avoid directly instantiating a class

3.6.14. Avoid creating non-essential objects

3.6.15. Avoid finalizer

3.6.16. Do not throw an exception from a no-parameter constructor

3.6.17. Do not add a displayed constructor to a published class

3.7. Setters and getters

3.7.1. Name a method that returns an access property whose value is not boolean, starting with get

3.7.2. A method to name an access property with a return value of boolean starting with is,can

3.7.3. Name a method that updates local variables starting with set

3.7.4. Check the parameters of the setter method

3.7.5. Minimize the work of getter and setter methods

3.7.6. Consider returning an immutable set from a getter method

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

3.7.8. Consider read-only attributes

3.7.9. Consider Defensive Copy when setting properties of a variable type (for more information on Defensive Copy, see http://www.javapractices.com/topic/TopicAction.do?Id=15)

3.7.10. Consider Defensive Copy when returning attributes of a variable type

3.7.11. The getter method avoids returning arrays

3.7.12. Avoid checking that cannot be completed according to the information in the method

3.7.13. Do not throw an exception from the getter method

3.7.14. Do not design set-only property methods (only public's setter and no public's getter)

3.7.15. Do not rely on the order of property settings

3.8. Callback

3.8.1. Use the most stringent preset conditions in design

3.8.2. Use the weakest post-conditions in design

3.8.3. Consider the callback interface as the first parameter in the method of passing the reference object

3.8.4. Avoid callback methods with return values

3.9. Document

3.9.1. Provide Javadoc comments for each method

3.9.2. Follow the standard Javadoc convention

3.9.3. Each method is summarized in a short sentence.

3.9.4. Declare the relevant methods

3.9.5. Declare obsolete types with the @ deprecated tag

3.9.6. Show alternatives to all outdated methods

3.9.7. Avoid lengthy zhus

3.9.8. Contains common usage patterns

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

3.9.10. Contains the type of method (stateless, accessor, or extension)

3.9.11. Contains preset conditions for the method

3.9.12. Contains the performance characteristics of the algorithm implementation

3.9.13. Include remote method calls

3.9.14. Contains methods to access external resources

3.9.15. Contains which API can be used in callbacks

3.9.16. Consider including unit tests to describe the behavior of the method

The above is the whole content of what Java API's design list is. For more content related to Java API's design list, you can search the previous articles or browse the following articles to learn! I believe the editor will add more knowledge to you. I hope you can support it!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.