General Design Rules
These rules describe basic concepts used in Apache OpenOffice API design. They are mandatory for all Apache OpenOffice contributions. They are recommended good practice for development of third-party software.
Universality
It is preferable to design and use universal interfaces instead of specialized ones. Interface reuse should prevail. Whenever a new interface is about to be created, consider the possibility of similar requirements in other application areas and design the interface in a general manner.
Orthogonality
The functionality of interfaces should extend each other. Avoid redundancy, but if it leads to a major simplification for application programmers, proceed. In general, functionality that can be acquired from basic interfaces should not be added directly. If necessary, create an extra service which provides the functionality and works on external data.
Inheritance
All interfaces are derived from com.sun.star.uno.XInterface. Other superclasses are only allowed if the following terms are true:
- the derived interface is a direct extension of the superclass
- the superclass is necessary in every case for the interface and inheritance if it is logical for the application programmer
- the superclass is the only possible superclass due to this definition
Uniformity
All identifiers have to follow uniform rules for semantics, lexical names, and order of arguments. Programmers and developers who are familiar with any portion of the API can work with any other part intuitively.
Correct English
Whoever designs API elements is responsible for the correct spelling and meaning of the applied English terms, especially for lexical names of interfaces, methods, structures and exceptions, as well as members of structures and exceptions. If not absolutely certain, use Merriam-Webster's Dictionary (https://www.m-w.com). We use U.S. spelling.
Mixed capitalization or underscores (the latter only for lexical constants and enumeration values) are used to separate words within single identifiers. Apply the word separation appropriately. English generally does not have compound words, unlike, for example, German.
Identifier Naming Convention
For common naming of identifiers, and to prevent potential restrictions for identifiers in UNO language bindings, a general naming convention has been defined. This naming convention allows a restricted set of identifiers, where no problems in any language bindings are expected. However, this cannot be guaranteed.
See the following pseudo-grammar, which shows, in a short but precise form, the permitted set of identifiers.
r* : zero or more r's, where r is a regular expression r+ : one or more r's r? : zero or one r (that is, "an optional r") r|s : either an r or a s [abc] : a "character class"; in this case the pattern matches either an 'a', a 'b' or a 'c' [a-z] : a "character class" with a range; matches any letter from 'a' through 'z' "xy" : the literal string xy (r) : match an r; parenthesis are used to override precedence DIGIT [0-9] CAPITAL [A-Z] SMALL [a-z] ALPHA CAPITAL|SMALL IDENTIFIER (ALPHA(ALPHA|DIGIT)*)|(CAPITAL("_"?(ALPHA|DIGIT)+)*)
The following examples of valid and invalid identifiers should make the preceding grammar clear.
Valid identifiers:
- getByName
- XText
- XText_2
- CLOSEABLE
- FATAL_ERROR
- Message
Invalid identifiers:
- _getByName
- _Name
- _name
- get_Name
- myName_2
When you define your own IDL specification, you should take this naming convention into account.
Content on this page is licensed under the Public Documentation License (PDL). |