API design in the software system in the importance of self-evident, in swift.org saw an "API design Guidelines", although in the case of Swift, but for other languages also have a lot to learn from the place, here roughly translated one or two, for communication purposes, comparative with the sex, Some deletions, if you need to see the original, please visit https://swift.org/documentation/api-design-guidelines/.
API Design Guidelines Basic Principles
- Clarity is the first priority. API methods and properties are declared, called everywhere, we need to design the use of simple and clear. When we evaluate a design, it is basically not enough to see its statement, and it is often necessary to place it in a specific usage scenario to ensure clarity when used.
- Clarity is far more important than simplicity. Although the code can be written in a compact, but the least characters to write the fewest code is not our goal, if the SWIFT code concise, it is a byproduct of the strongly-typed system, can reduce boilerplate code.
- Each declaration is annotated with a document. Writing a document can enhance your understanding of the design without delaying it. If you find that you cannot simply describe the functionality of the API (bad smell), there are likely design problems.
(Swift code comments suggested, omitted)
Naming is more clear.
- Include all the necessary words to avoid confusion.
- Ignore unnecessary words. Each word in a name has significant implications for the user.
- For variable names, parameter names, and reference type names, they should be named according to their role, not their constraints.
- Supplement the weak type parameter information to make the parametric role clearer (such as adding a noun to the parameter name to describe the role).
Strive to use fluency
- The method name or function name should be used in the form of English grammar as much as possible.
- The factory method name starts with "make".
- The phrase formed during the initialization method and the factory method call should not contain the first argument.
- Named according to the joint result of the method or function.
- If there is no joint outcome, it should be a noun name.
- If there is a joint outcome, it should be a verb named.
- Mutable and non-mutable methods should have a consistent format for naming.
- For immutable Boolean types, methods or properties should be the form of assertions, such as X.isempty.
- The agreement describing the thing should be named by the noun.
- The protocol describing the ability should be able, ible, or ing as a suffix.
- Other types, variables, attributes, and nouns of constants should be named by nouns.
Use good terminology
- Avoid obscure terminology and describe it in a way that is easy to understand.
- The terminology should be used in a proper place.
- Do not use abbreviations.
Convention General Practice
- The computed attribute of the complexity not O (1) should be commented to describe its complexity.
- Use methods and properties preferentially, minimizing the use of functions.
- Following the casing conventions, the naming of types and protocols should be capitalized on the hump, and the other should be named after the first letter of the hump.
- Method names can share a basic name if these methods have a common basic meaning.
Parameters
- Facilitates document annotation, facilitates reading.
- You can use the default parameter values when you suppress the usual usage.
- Parameters with default parameter values should be placed after the parameter list.
Parameter label (Swift, omitted) special description
- Closed-loop parameters and tuple members should be set to label (Swift).
- Use unrestricted polymorphism sparingly to avoid confusion in the event of overloading. Use any, the name that begins with caution.
API Design Guide (translation)
