Naming Standards

Colin McCrone edited this page Apr 1, 2015 · 5 revisions

This document provides standards and guidelines for naming categories, nodes, and input and output ports in Dynamo. The core libraries of Dynamo will be renovated to reflect these standards. External developers are free to take these rules as suggestions.

Library and Categories

Names of libraries and categories should be capitalized.

Spaces are okay.

Subcategories

Create subcategory contains constructors. These nodes create the given object from other types of inputs. These have keyword “By” at the beginning of their name.

  • Ex: A create-type node for a point always makes a point, and never has a point input.

Action subcategory contains class methods, which operate on that object type Code Block-callable nodes of this category must list the port for the object it operates on first. Ex: Point.Add’s first input is point.

  • Ex: Point.Add is an action-type node because it does something to a Point.

Query subcategory contains nodes to access properties about an instance of that object

  • Ex: Point.X is a query-type node because all points have an x-component, and this just get that property of that point. Nothing else is made or calculated.

Node Names

Strive for brevity. Don’t use more words when fewer will do.

  • Ex: List.ItemAtIndex not List.GetItemAtIndex

Strive for clarity.

Avoid redundancy.

  • Ex: Line.ByTwoPoints not Line.ByStartPointEndPoint

No abbreviations except for the list of always-acceptable math and range abbreviations (see list below). Conditionally-acceptable abbreviations are not allowed in node names.

  • Ex: DateTime.Min is okay because “Min” is an always-acceptable abbreviation.
  • Ex: Vector.ByTwoPoints not Vector.ByTwoPts because “Point” is a conditionally-acceptable abbreviation.

Create-type nodes should have “By” at the beginning of their name unless there is a good reason otherwise. Other nodes should avoid the word “By”.

  • Ex: Point.ByOrigin not Point.Origin

Inputs referred to in a name should follow the order of their appearance in the node itself.

  • Ex: Circle.ByCenterPointRadius has inputs [0] centerPt and [1] radius

Use parallel structures for like functionalities.

  • Ex: Element.SetParameter and Element.GetParameter

Refer to the action in the present tense, not as if it had already happened.

  • Ex: Vector.Normalize not Vector.Normalized
  • Ex: PolyCurve.ByCurves not PolyCurve.ByJoinedCurves

No “And” in the name.

  • Ex: Circle.ByCenterPtRadius not Circle.ByCenterPtAndRadius

Non UI-enabled node names use dot notation if and only if they can be called from a code block. UI nodes and other special nodes that are not callable from a code block should use spaces between words.

  • Ex: List.Count can be called from a code block, but Watch Image is a UI-enabled node, so no dot is used and spaces are acceptable.

Capitalize each word.

  • Ex: Math.DegreesToRadians not Math.degreesToRadians

Port Names

Use full words unless abbreviations are allowed and shortened forms do not compromise clarity.

When an abbreviation is used, the full term must appear first in the tooltip for the port.

Definitions:

  • degrees: for angles in degrees
  • function: ports which accept a function rather than data
  • geometry: when the type is not always known, such as in an intersection operation
  • number: a double value
  • radians: for angles in radians
  • result: result of applying a function
  • str: the word always used for “string”; note this is an exception to the abbreviation policy
  • value: when the type is not known. Ex: for known double values use number

Use camel case. The form of an input port name often matches the data type (ex: color is a name, while Color is a type and a reserved word). Using camel case helps to distinguish an instance from the type.

  • Ex: point not Point
  • Ex: filePath not FilePath or Filepath

All name-lists should be zero-indexed.

  • Ex: list0, list1, list2,…

Output ports use the name of the data type unless otherwise indicated by the developer. Unless more specificity is needed, output ports should list the data type

  • Ex: Point.ByCartesianCoordinates yields Point, which is the name of the data type. Should the developer chose, a special name could be used.

Indicating Quantity

Always use the singular form of the word for port names in order to indicate the least-complex acceptable data type. If a single item is an acceptable input, only use the single form of the word and nothing to indicate plurality.

  • Ex: Circle.ByCenterPointRadius has ports centerPt and radius, each of which is singular even though lists can be passed to them, in which case replication behavior results.
  • Ex: Vector.ByTwoPoints has a plural word in the node name, which is fine, but the port names are singular, start and end.

Data that must be in the form of a list must use the word “list” in the port name. If the type is known or if any other name is used, *List must be appended to the end of the name.

  • Ex: Element.Geometry always returns a list, even if the list only contains one item, so its output port should read geomList not geometry or geometries. Note that since “geometry” has a conditionally-acceptable abbreviation, the shortened form can be used with “List”.
  • Ex: List.Transpose operates on and produces a list of lists that may contain any type. The simplest description for both input and output ports is therefore listList.

Abbreviations

Always acceptable abbreviations:

  • Range: min, max
  • Trigonometry: sin, cos, atan, sinh, etc…
  • Standard math: exp, abs, log, log10, pow, sqrt
  • Strings: str

Conditionally-acceptable abbreviations are those which can occur only when a word is not by itself.

  • Ex: The port name point cannot be abbreviated, but startPoint can be abbreviated as startPt since the word “point” is used together with the word “start”.
Abbreviation Long-form Example
bool boolean bool0, bool1,…
char character padChar
coord coordinate coordSys
comp component adaptiveComp
crv curve guideCrv
elem element hostedElem
func function conditionalFunc
geom geometry geomList
num number num0, num1,…
param parameter startParam
pt point startPt
ref reference refPlane
srf surface projectionSrf
struct structural structFramingType
sys system coordSys
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.