SECTION: Webel coding and naming conventions for the Wolfram Language

Icon class
icon_class_computed
far fa-bookmark
Tutorial
[TECHNICAL SLIDE TRAIL] The Webel libraries for Wolfram Mathematica: With SysMLv1 models.
Keywords
Please make sure you've read the intro page about this highly technical trail on the Webel libraries for the Wolfram Language and SysML4Mathematica.

This SECTION is provided primarily for reference and may be skipped in favour of sections with application examples. Many examples of the use of the conventions explained in detail here appear in other slides. However, if you wish to understand why the Webel libraries for the Wolfram Language and Mathematica are coded as they are, this SECTION is essential reading!

This trail SECTION has many cross-links to the supporting Webel SysML4Mathematica (v1) policy and convention note pages.
Start section here
DRY not WET! "Don't Repeat Yourself!"

Slides in this section

If you want to navigate the entire section including the additional explanatory text click on the title link of the first slide to view the full slide page, then use the next links to move through the slide pages. If you just want to view the slide images only in sequence, click on any slide to view it larger in a viewer, then click again to move through each slide in this tutorial trail section.
DRY not WET! "Don't Repeat Yourself!"
The Webel ‘$’ prefix convention for Strings and "String similar" Wolfram Language code
The Webel $k$ prefix convention for Association String keys
The Webel ‘$pat$’ pattern helper convention for frequently used Patterns
The Webel ‘$t$’ “pseudo type” indicator String convention (for optional additional documentation only)
Webel ‘$info$f$’ prefix convention for function help holder Strings
Webel ‘def$’ DRY default capture! Applicable to arguments and options.
Next trail section
SECTION: The Webel '$opt$' and '$arg$' help holder conventions for options and arguments in the Wolfram Language
Webel: Mathematica: CONVENTION: A 'type$' indicator for an '$opt$' or '$arg$' is for documentation only. It may use a "pattern helper", a human-friendly String, or a SysML-similar short-hand type representation. It need not correspond to a valid Pattern.
Webel: Mathematica: CONVENTION: A '$Q$' in a function variant name indicates that it is a variant where every argument is strictly either a Quantity or dimensionless Real. Compare with '$SI$' functions.
Webel: Mathematica: CONVENTION: An '$E$' or '$EQ$' in a function name indicates that it is symbolic (takes Blank expression arguments), but the absence of '$E$' or '$EQ$' does not necessarily imply that it does not take Blank arguments.
Webel: Mathematica: CONVENTION: MTools classes: A 'z' prefix indicates a "private" method; A 'my' prefix indicates a "protected" method (typically a protected hook). There is no actual visibility enforcement other than by name convention.
Webel: Mathematica: CONVENTION: An '$SI$' in a function variant name indicates that all arguments are SI Real convention (no Quantity arguments with units). An '$SI$' function can also be used to generate '$C$' compiled function variants.
Webel: Mathematica: CONVENTION: A '$C$' in a function name indicates that it is a compiled variant. Typically it is compiled from an '$E$' symbolic function or an '$SI$' Real convention function.
Webel: Mathematica: CONVENTION: An '$E$' in a function name indicates that it is symbolic (takes Blank expression arguments). An '$E$' function can also be used with Quantity inputs and can be used to generate '$C$' compiled function variants.
Webel: Mathematica: CONVENTION: A '$EQ$' in a function name indicates that it is a symbolic equation (with LHS == RHS). An '$EQ$ function can be used in combination with 'sym$' markup to create human-friendly formatted equations.
Webel: Mathematica: CONVENTION: Entity "field definers" are prefixed with '$e$[pac]' (where '[pac]' is a nickname for a package or logical grouping) and carry String field names. EntityStore functions are prefixed with 'e$[pac]'.
Webel: Mathematica: Packages that import the Webel HelpF` package (but not MTools and the Webel HelpM` package) should use the 'usageF' function for ::usage String generation (rather than the 'docF' and 'docV' functions) and an AOR Map.
Webel: Mathematica: CONVENTION: A '$sig$f$' prefix indicates a String signature helper for a function (or for a "method" of an MTools class or a Webel Abstract Data Type (ADT) pseudo class).
Webel: Mathematica: CONVENTION: A '$doc$' prefix indicates a formatted documentation String helper. A '$doc$arg$' is for an argument, a '$doc$opt$' is for an option. A '$doc$ String may be used to create ::usage documentation via docF.
Webel: Mathematica: CONVENTION: A ‘$pac$’ String helper variable is used to capture the fully qualified String name of every package. Useful for quick '$pac' argument provision for search functions and for DEVEL package load echoes.
Webel: Mathematica: CONVENTION: A 'z$' prefix may be used to indicate a Private` function or expression within a package or a "private" method of an MTools class or Webel Abstract Data Type (ADT) stateless pseudo class.
Webel: Mathematica: CONVENTION: The Stereotype keyword «functional» indicates a "pseudo functional" representation of functional in SysML. There are limits to representation of functional programming in SysML, but it can be informative and is worth doing.
Webel: Mathematica: CONVENTION: A '$t$' prefix indicates a String help holder with a "pseudo type" indicator (for human friendly documentation only). Used by the Doc`, HelpF`, and HelpO` packages.
Webel: Mathematica: CONVENTION: A function's description (but not its signature, arguments, or options) may be captured as an '$info$f$' Stringhelp holder for use by the Doc` package for ::usage generation and the HelpF`& HelpO` help registry packages.
Webel: Mathematica: A help Rule 'rule$opt$' for an '$opt$' (option) accepts keys: '$k$help' (required), '$k$def' (required), and optional '$k$warn', '$k$tip', '$k$lab' (a label), '$k$type' (indicator only), '$k$mult' (SysML multiplicity), and '$k$pat'.
Webel: Mathematica: A help Rule 'rule$arg' for an '$arg$' (argument) accepts keys: '$k$help' (required), '$k$def' (required if $k$req = True not given), '$k$req' (True if $k$def not given), '$k$warn', '$k$tip', '$k$lab', '$k$type', '$k$mult' and '$k$pat'
Webel: Mathematica: CONVENTION: An '$opt$' (option) or '$arg$ (argument) help holder may be have an associated (typically short) '$lab$opt$' or '$lab$arg$' label help holder for use in GUIs and views.
Webel: Mathematica: CONVENTION: Where keys of Associations are Strings they are encapsulated as variables prefixed with '$k$' (promotes DRY and has many advantages, such as IDE prompting). Direct use of "Strings" as keys is WET and strongly discouraged!
Webel: Mathematica: CONVENTION: "pattern helpers" (which are not themselves Patterns) use the prefix '$pat$. Encapsulated Patterns use a 'pat$' prefix, and may use a '$pat$' pattern helper (such as an Alternatives).
Webel: Mathematica: CONVENTION: Argument help holders use a String variable with the prefix '$arg$', a related '$info$arg$' String, a 'def$arg$' default value expression and/or 'req$arg$', and optional '$warn$arg$', '$tip$arg$, '$lab$arg$', 'type$arg$'..
Webel: Mathematica: CONVENTION: Option help holders use a String variable with the prefix '$opt$', a related '$info$opt$' String, a 'def$opt$' default value expression, and optional '$warn$opt$', '$tip$opt$', '$lab$opt$', and 'type$opt$' indicator ...