Naming conventions

Nodes within Metrici can have any name and any reference that conforms to the rules described in Node references.

However, it is useful to define some guidelines for the names and references for nodes, and how they are referred to in scripts and bindings.

Most nodes fall into one of a number of roles, such as:

  • Node types
  • Member types (or fields)
  • Scripts
  • Tags
  • Views
  • Packages
  • Constants

The general naming convention is:

  • Start with a descriptive name in title case, e.g. "My Node".
  • Add a node role as the last part of the name, e.g. "My Node Role".
  • Remove spaces to give the node reference, e.g. "MyNodeRole".
  • When referenced in a script or as a binding, the role name in lower case goes first, e.g. "roleMyNode".
  • Where names are shown to users, use sentence case and omit the role from the name (but not the reference), e.g. "My node".

For node types:

  • Use a role of Type.
  • Use title case for the name, but omit the role name. This makes the node type more readable. (For example, Fred's node type is Person).

For member types/fields:

  • Do not include a role at the end of the name or reference.
  • For fields shown to users, the name is in sentence case, i.e. only the first letter of the first word capitalised.
  • For fields where the headings are not shown to users (for example, derivation fields), the name is in title case.
  • Use a role of "mt" (for member type) when referencing the member type in a script or binding.
  • If you are linking to a node which would typically have a role (e.g. Type), then use RoleLink at the end of the local reference, for example UserWrapperTypeLink, to avoid potential reference clashes.
  • If the field would end in a role name, rename it or add the role name Field.

For tags:

  • Use a role of Tag.
  • Do not include the role name in the name.
  • Use sentence case for tags intended to be viewed by users.

For packages:

  • Use an appropriate short, descriptive name.
  • Use sentence case, as this is easier to read, especially in the breadcrumb trail.
  • Base the reference on the name, in lower case, with underscores. This is easiest to read in a URL. Do not add a role suffix.
  • Packages are not generally referenced in scripts, but when referenced in bindings can use any suitable name, such "project" or "settings".

For scripts:

  • Use a role of Script.
  • If the script has a more specific role (such as a column script or a task script), use that in place of the general Script role. For example, a task script to refresh calculations might be called "Refresh Calculations Task Script", with a reference of "RefreshCalculationsTaskScript", and an in-script name of "taskScriptRefreshCalculations" (not "scriptRefreshCalculationsTask").
  • If the script is intended as a runnable service, not a class or a script that produces UI content, and generally acts like the built-in services, use a role of Service.

For constants (such as targets, statuses, etc):

  • Use a role if it makes sense (such as Status), but not where there is no meaningful role.
  • In the name, use sentence case and omit the role if to be shown to users.
  • Within scripts, use a role prefix of "constant" if there is no other role.

The conventions for references are more important than those for names. For example, if you have a column script to show total price, its reference should be "TotalPriceColumnScript", but you could call it "Total price". References for member types often need indicate a data type. For example, "Favourite vehicle" might have a reference "FavouriteVehicleIndicator" if it were a boolean, or "FavouriteVehicleLink" if it were a link to a favourite vehicle node. Within a script, continue to use the mt prefix, e.g. mtFavouriteVehicleIndicator not indicatorFavouriteVehicle.

Some things (especially grades in assessment solutions) can have very long names. In this case, you might want a shorter reference than the name.

There are no conventions for general data or content nodes. If they are permanent nodes (for example, documentation), using references in lower case with underscores is generally the clearest.

Examples

Role Name Reference Script name
Type Vehicle Manufacturer VehicleManufacturerType typeVehicleManufacturer
Member type/field Vehicle model VehicleModel mtVehicleModel
Script Calculate Average Consumption Script CalculateAverageConsumptionScript scriptCalculateAverageConsumption
Tag Favourite vehicle FavouriteVehicleTag tagFavouriteVehicle 
View Makes And Models View MakesAndModelsView viewMakesAndModels 
Package My vehicles my_vehicles -
Constant - defined role, e.g. status In progress InProgressStatus statusInProgress
Constant - no defined role, e.g. target of a selection I want to include this vehicle in my list of favourites IncludeInFavourites constantIncludeInFavourites

Acronyms and proper nouns

Acronyms or abbreviations are often used in solutions. When capitalising these, remember that the entire acronym should be capitalised whether it is in title or sentence case. Similarly, the first letter of proper nouns (names of specific things) should be capitalised in names.

So, for example, if you have a field to hold export XML, you would call it "Export XML", reference "ExportXML", and name within a script "mtExportXML".  Do not call it "Export Xml". If it was a package, you would call it "export_xml", all in lower case.