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).
  • If the instance is a node type, use a role of TypeType. For example, MemberTypeType is used to create MemberTypes which are used to create members.
  • If the thing that the node represents is called a type, but is not a node type, use something like "TypeOfXXXX" as the local reference. For example, a node type that records a type of vehicle, you might use a local reference of "TypeOfVehicleType", but call the node type "Vehicle Type".

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 example, if you had a field you use to categorise products which you want to call "Product type", give it a reference of ProductTypeField or TypeOfProduct.

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.

For views:

  • Use a role of View.
  • Use title case.
  • Name the view in the singular. For example, a view used in a table of projects should be "Project View" not "Projects View".

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 Model View MakesAndModelView viewMakesAndModel 
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.

International spelling

In references, but not necessarily names, prefer international spelling in place of British English where the international spelling is acceptable or more commonly used. In particular, use the -ize ending, which is perfectly acceptable in British English, and use "color" because colour is always referenced "color" in standards (e.g. HTML).