Naming conventions

From Cloudrexx Development Wiki
Jump to: navigation, search

This article is part of the currently approved draft of the development guidelines!

This article describes the naming conventions for Contrexx development.

General

  • Use of clever names makes everything easy! For example '/modules/Demo/Controller/DemoModuleController.class.php' would be a stupid filename, because everything the filename consists of is already contained in the file's path. Use something like 'modules/Demo/Controller/Frontend.class.php' instead. If you work on the Demo module, you hopefully will know what module you are working on, and it should be obvious if the file is part of model, view or controllers.
  • Avoid keywords of all used languages (PHP keywords, JS keywords), because they can cause trouble when used in namespaces or as a class, interface or attribute name.
  • Always use singular names. Use the singular form of the noun to label something (component name, variable, class, etc.)

All names (component names, variables, classes, methods, HTTP parameters, ...) are written in one of the following ways. Never mix these notations! A string can be converted between each of those, without any loss of data:

CC: Camel case

CC strings are written in lowercase, except for first letter per "word". Examples would be 'Url' for 'URL', 'ClassLoader' for 'Class loader', etc.

CCL: Camel case, starting with a lowercase letter

CCl notation works like CC, with the exception that the first letter is lowercase. Examples would be 'url' for 'URL', 'classLoader' for 'Class loader', etc.

USL: Underline separated, lowercase

USl notation splits all words with an underline character ('_'). All characters are written in lowercase. Examples would be 'url' for 'URL', 'class_loader' for 'Class loader', etc.

USU: Underline separated, capital letters

USu notation is the same as USl, except that all letter are written uppercase. Examples would be 'URL' for 'URL', 'CLASS_LOADER' for 'Class loader', etc.

USC: Underline separated, camel case

USc is a mixture of USu/l and CC. Words are separated using camelcase, but special characters are replaced by an underline. Example would be 'Http_1_0' for 'HTTP 1.0'.

HR: Human readable

By human readable, we mean a notation that is quite similar to the English writing. Since the software does not now the English grammar, there might be some mistakes with upper and lower case.

HR notation starts with a capital letter, all the following letters are written in lowercase. "Words" are separated by a space. Examples would be 'Url' for 'URL', 'Class loader' for 'Class loader', etc.

HS: Hyphen separated

HS strings are written in lowercase and separated by a hyphen (-). Examples would be 'url' for 'URL', 'class-loader' for 'Class loader', etc.

More examples

English CC CCL USL USU USC HR HS
URL Url url url URL Url Url url
Class loader ClassLoader classLoader class_loader CLASS_LOADER ClassLoader Class loader class-loader
HTTP 1.0 Http10 http10 http_1_0 HTTP_1_0 Http_1_0 Http 1 0 http-1-0
... ... ... ... ... ... ... ...

How to write what

Here's a table showing how to write what. Things that needed further information are listed below. This table is not limited to PHP.

What Notation to use Reason
Namespaces CC ...
Classes, Interfaces and Traits CC ...
Class attributes and variables CCL ...
Class constants USU ...
Methods and Functions CCL ...
Components CC ...
DB names, tables and attributes USL ...
DB ENUM and SET values USU ...
HTTP parameter names CCL ...
Files and folders CC ...
Template placeholders USU ...
Template blocks USL ...
cmd/section CC ...
HTML attributes, classes, ids, names HS ...

Namespaces

Use namespaces that match the class's or interface's location in the file system. This allows the ClassLoader to auto-load this file without unnecessary searching.

Methods and Functions

Since private and protected functions do not exist, functions that are only used in a scope that could be described as 'private' or 'protected' start with an underline to indicate that fact.

Since private and protected methods DO exist, methods starting with an underline are meaningless and should be avoided.

Events

Events constist of up to 3 parts following the scheme <component>[.<entity>]:<action>

Placholder type wordtype usage meaning
component CC Noun Add always Use the name of the component which registers the event
entity CC Noun Add if the event belongs to an entity or part of the component Name of the related entity or part of the component
action CCL Verb in imperative form Add always Describes what happened just before this event was triggered

Examples:

  • MediaBrowser.Plugin:initialize
  • Cache:clear
  • Model:prePersist

Components

Be sure you don't use a reserved PHP keyword (see General) or the name of an existing module, core_module, or core component.

Database tables

The name of a database table must follow the following scheme (USL notation):

DBPREFIX[core|core_module|module]_{COMPONENT_NAME}_{ENTITY_NAME}

Example: contrexx_core_module_news_article (whereas DBPREFIX is set to contrexx_)

Files and folders

Files of course end with a type specific suffix. For PHP files, the ClassLoader requires the ending '.class.php' or '.interface.php' for classes/interfaces to load properly.

Template placeholders

The general naming scheme for placeholders is as follows (USU notation):

[[{COMPONENT_NAME}[_{SECTION}]_{OBJECT_NAME}[_{OBJECT_ATTRIBUTE}]]]

A few examples:

  • [[ACCESS_USER_ID]]
  • [[ACCESS_SETTINGS_MESSAGE]]

Placeholders used for the Interface Text of the GUI do use a special naming scheme. Refer to the article Text-Variable.

Template blocks

The general naming scheme for placeholders is as follows (USL notation):

<!-- (BEGIN|END) {COMPONENT_NAME}[_{SECTION}]_{OBJECT_NAME}[_{OBJECT_ATTRIBUTE}] -->

A few examples:

  • <!-- (BEGIN|END) access_sociallogin_provider -->
  • <!-- (BEGIN|END) access_signup_confirmation_success -->