General Design Rules

From Apache OpenOffice Wiki
Jump to: navigation, search



These rules describe basic concepts used in OpenOffice.org API design. They are mandatory for all OpenOffice.org 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 (http://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.

Documentation caution.png You will find incorrect identifiers in the current API, but this cannot be changed for compatibility reasons. Nevertheless, you should adhere to this naming convention for your own IDL specifications.


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages