Created by lissensj on May 21, 2014

Java-like Rules and Conventions

Even though QDMs are language-independent, Java naming rules provide an excellent guide for naming namespaces, data types and fields. We recommend therefore to adhere to these rules as much as possible. The rules are described here:

http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-135099.html. 

Below is an overview of how these naming conventions apply to Qeo:

Namespace (Module)

Use the following rules of thumb:

  • Use only lowercase characters in namespace identifiers
  • Start each namespace with your domain name in reverse
  • Use org::qeo::* only for standardized models destined for the official QDM repository
Struct

Use the following rules:

  • Use UpperCase for type names

    Icon

    This is actually more than a rule of thumb. The use of capitals is required and enforced by the Code Generator.

  • Type names should be nouns or concatenations of nouns

Use the following rules of thumb:

  • Avoid useless words in the name
  • Do not repeat information that is already apparent from the module name, 
    e.g.: In the Media Endpoint example, we use Endpoint as struct name within the Media module and not MediaEndpoint, since this would repeat the media part
  • Do not add State or Event to the name to mark a struct's behavior.
Struct Member Field Names

Use the following rules of thumb:

  • Avoid the use of underscores
  • Use lowerCamelCase for member names
Example

Consider the example below::

<module name="com::technicolor::MediaEndpoint">
	<struct name="MediaEndpoint">
		<member name="mediaEndpointId" type="string" key="true">

This example violates the above rules in a number of ways:

  • the namespace com::technicolor::MediaEndpoint is not in all-lowercase
  • useless repetition: the words "media endpoint" appear in the namespace, the type name and the member name. Based on this example, the Qeo code generator will generate a C struct called com_technicolor_MediaEndpoint_MediaEndpoint whose first member will be a field called mediaEndpointId. Developers working with the above data model will for sure appreciate a more concise naming scheme.

A better way to define the above model is:

<module name="com::technicolor::media">
	<struct name="Endpoint">
		<member name="id" type="string" key="true"> 

This model uses unique names.

Language-related Guidelines

Use of Acronyms and Initialisms in Camel Case Identifiers

Often, type or member names will include some kind of acronym or initialism (e.g. HTML, DB, IPaddress, ...). The Qeo convention is to treat these acronyms as "regular" words, subject to the regular camel case rules.

For example:

  • if you define a type that represents an HTML file, call it "HtmlFile", not "HTMLFile"
  • if you define a struct member that represents an IP address, call it "ipAddress", not "IPAddress" or "iPAddress".
Don't Use Gratuitous Abbreviations

If you use abbreviations in type or member names, do so only if the abbreviation is widely understood and commonly used. It's perfectly fine to use HTML or IP as abbreviations, but don't use "temp" instead of "temperature".

Language and Spelling

In general, use English words for identifiers. Always use U.S. English spelling when there are different ways to spell a given word.

For example:

  • use caliber instead of calibre
  • use license instead of licence