Conventions/code/naming

I tend to use the following naming conventions within my code.

Prefixes

These are more or less in keeping with the Apps (original) variation of Hungarian notation.

Variable Prefixes

• dl: an integer length (typically of a string)
• dx: an integer position (typically of a string)
• f: floating-point number
  • Was also used for functions, but I have changed to fx for that.
• ft: formatted (meaning marked-up) text string (could be HTML, could be wikitext...)
• fx: function variable (function stored in a variable, as in PHP/function variable)
• ht: HTML string
• k or K: a constant, i.e. anything whose value should not (or cannot) change once defined
• n: a count (int; use f for float)
• o: object
  • or: a ref object (see Value Types)
  • os: a status object (see Value Types)
• s: string
  • sc: string that is the name of a class
  • sq or sql: string formatted as SQL, or safe to be used within SQL
• url: string formatted as a complete URL
• uri: string formatted as a URI, i.e. part of a URL
• wt: wikitext-formatted string (in whatever wiki markup is applicable)

Possibly all numbers should start with n and then the type: ni, nf, nc

see also General Affixes

Type Prefixes

• c: class
  • ca: abstract class (cannot be instantiated)
  • cn: class that is a wrapper for the results of a native function
  • cs: static class (not intended to be instantiable; all methods static)
• cb: callback function (used in the function name itself, rather than in variables referring to it)
• ch: a string that is always a single character
• f: [DEPRECATED; use namespaces instead]: a Ferreteria class/trait/interface
• if: interface
• t: trait
  • ta: trait that introduces abstract functions (so any class using it will become abstract unless it implements them)
  • ts: trait that introduces static functions

I wanted to use "c1" (cee-one) as a prefix for singleton classes (i.e. a class for which there should never be more than one object), but it looks too much like "cl" (cee-ell) or possibly a typo, so I dropped that idea. (For future exploration: maybe "co" would work.)

General Affixes

In the prefix but not necessarily as the first characters:

• db: a database
• rc: a single-record class/object
• rs: a recordset class/object
• t: a table class/object

These may be used in declarations or variable names, but are generally used only for classes and objects. For classes, the c prefix comes first; for objects, these replace the o prefix, and sometimes may be the entire name of the variable.

Value Types

• actual means a reference-container object
  • I prefer this to "reference" where possible. It's shorter, less misleading (all PHP variables are references), and correctly implies that the entity in question is the actual thing and not a copy.
• cell means access to a value in a named location (e.g. an array element)
• ref is another shorthand for "reference"; see "actual".
• slug means a string which can unambiguously represent any expected value or state of a given item
  • needed for representing record IDs in URLs, where one possible state is "new" (no ID yet)
• status means a presence-info object
  • preferably descended from cThingHolder
• unit means something that knows its own name and has awareness of its container-object/structure
  • preferably a PortRow Unit object
• value means a read-only value, assumed to exist (throws error if not)

Actions

I try to be consistent with the shades of meaning in affixes within function names. Newer code is better about this than older code.

• Get: retrieve a value or value-set; should not change anything
• Set: overwrite a value or value-set; in the case of a named value-set, existing values not written by corresponding input values should be cleared/erased
• Use: include the following value(s) in the target value-set; existing values will be preserved unless overwritten by an eponymous input
• [verb]Array: just copy the given array, don't process individual elements
• [verb]Cells: handle individual elements
  • Some older code uses "Values".
  • Note that a Cell can sometimes be a varstat object.
• Create: construct a new object, always
• Build is mostly synonymous with "create" but implies that the process may be more complex
• Make means "build/create if that hasn't already been done, and return the object"

The distinction between "Set" and "Use" really only comes into play within named value-sets (arrays of various sorts where each element has a sematically-significant name).

Namespace Aliases

When creating an alias for a namespace, I use capital letters to indicate that the namespace is an alias. (For a little while, I only used caps for parents of the current namespace, but this got confusing and made code less portable.)

Examples:

use ferret as F;
use ferret\data as FD;

I've established conventions for certain frequently-needed types of namespace aliases, to make it easier to copy/paste code for new classes:

• _PC: namespace of the parent class for the main class in this file
• _P or _PF: parent namespace, i.e. namespace's parent folder -- e.g. for ferret\data\bank, _P would be ferret\data.
• _FEAT: the namespace for the main Feature class (Ferreteria-specific)