The idea behind the coding convention is that a developer should be able to see when something is wrong. Either when something from another scope is used without validation (parameters in public methods, for instance) or when a certain type is addressed as though it were another type.
To link to this convention from code, the following header is recommended:
/** * @NOTE: The variable naming scheme used in this code is an adaption of * Systems Hungarian which is explained at http://blog.pother.ca/VariableNamingConvention/ */
The convention used for variables is a derived form of Systems Hungarian notation that consist of a 3 part prefix: the Scope of a variable, a Delimiter, and the Type of a variable.
For variables in a closed scope (usually a function) the Scope and Delimiter are omitted and only the Type is prefixed.
A delimiter is added in order to separate the scope from the rest of the name. This delimiter is a conscious eyesore to make variables from other scopes stand out, as using variables from another scope can lead to painful situations.
Some languages require a variable name to start with a sigil. For developers used to such a language, Hungarian Notation will feel more natural than for developers used to languages that do not require sigils.
The letters used to denote the Scope and Type are explained in the “Scope” and “Type” sections below.
For the various languages this convention pertains to this gives us:
Strictly speaking the
$ character used in Bash isn’t truly a sigil
but “an unary operator for lexical indirection”. The effect,
however, is much the same.
To help identify where variables come from and for easier fetching of name-lists in scope-aware editors, a scope flag is prefixed to variables that aren’t in a function/method’s closed scope.
Available flags for the scope are:
|t||temporary variables||variables that are created only to be temporarily used and then overwritten or discarded, as often occurs in loops.|
|p||function parameters||Things from “the outside” can often not be trusted. This prefix helps to indicate when values move across scopes.|
|$||jQuery Object||JS||Other||Only relevant when working with code that uses the jQuery Library. |
|c||Callback||BASH/JS/PHP||Other||A callback, also known as a Function.|
|d||Double||BASH/JS/PHP||Scalar||A double, also know as a “Float”, a floating-point number.|
|j||(reserved)||JS||Other||Set aside just in case the
|n||Numeric||BASH/JS/PHP||Scalar||Can be either an integer or a numeric string .|
$has other significant, denoting a variable, parameter, property, or method that belongs to the core of Angular and prevent elements from being iterated (or interpreted) in certain directives.
jfor jQuery objects instead. That idea is still under revision.
-rflag. As Symbols/Constants are the familiar exceptional to the rule and do not adhere to this standard. they should be declared in so called SCREAMING_SNAKE_CASE6
The “Name” part of a variable should describe what the variable is in the problem domain it represents. Be as descriptive as possible but hold these two rules of thumb in the back of your head when coming up with a name:
Putting all of this together we get the following syntax diagram:
VariableName ::= ( [[email protected]%&]* ([gmpt] '_')* [abcdfijmnorsu$] [A-Z] [a-zA-Z0-9]+ )
Generated using the Railroad Diagram Generator
This convention has been evolving ever since Potherca started programming Perl in the mid-nineties and branched out into PHP in the early noughties. Yet it was never put into writing until encourage to do so by Sander Krause in 2009.
The Variable Naming Convention by Potherca and Sander Krause is licensed under the Creative Commons Attribution 4.0 International License .