| permalink | title |
|---|---|
/ |
Variable Naming Convention for weak and/or dynamic typed languages |
- auto-gen TOC: {:toc}
This document explains the naming convention meant to be used with dynamic and/or weakly typed languages (as defined in the Typing Quadrant on the Cunningham Wiki) such as PHP, Javascript, Perl, and Bash.
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:
| Language | Example | Sigil | Scope | Delimiter | Type | Name |
|---|---|---|---|---|---|---|
| BASH | $g_xFoo |
$ |
g/m/p/t |
_ |
x |
Foo |
| Javascript | g_xFoo |
g/m/p/t |
_ |
x |
Foo | |
| Perl | $g_xFoo |
$/@/%/& |
g/m/p/t |
_ |
x |
Foo |
| PHP | $g_xFoo |
$ |
g/m/p/t |
_ |
x |
Foo |
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:
| Prefix | Scope | Rational |
|---|---|---|
| g | global | |
| 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. |
| m | class members |
- More information about types in PHP is available in the PHP manual
- More information about types in Javascript is available in the MDN page on JavaScript data types and data structures
- More information about types in Bash is available in the Linux Documentation Project on the Bash Guide page about Types of variables
| Prefix | Type | Language(s) | Category | Notes |
|---|---|---|---|---|
| $ | jQuery Object | JS | Other | Only relevant when working with code that uses the jQuery Library. [1][2] |
| a | Array | BASH/JS/PHP | Compound | |
| b | Boolean | BASH/JS/PHP | Scalar | |
| c | Callback | BASH/JS/PHP | Other | A callback, also known as a Function.[3] |
| f | " | " | " | " |
| d | Double | BASH/JS[4]/PHP | Scalar | A double, also know as a "Float", a floating-point number. |
| i | Integer | BASH/JS[4]/PHP | Scalar | |
| j | (reserved) | JS | Other | Set aside just in case the $ character (for jQuery Objects) is to be replaced. See [2]. |
| m | Mixed | BASH/JS/PHP | Other | |
| n | Numeric | BASH/JS/PHP | Scalar | Can be either an integer or a numeric string [5]. |
| o | Object | JS/PHP | Compound | |
| r | Resource | PHP | Other | |
| s | String | BASH/JS/PHP | Scalar | |
| u | Unknown | BASH/JS/PHP | Other |
- In the Angular framework the dollar character
$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. - The fact that this character can lead to confusion as it is a sigil in other languages has lead to the idea that it might be better to use
jfor jQuery objects instead. That idea is still under revision. - In Bash this refers to variables declared with the
-fflag. - Javascript only has one "Number" type which is used for both floating-point numbers and integers
- A string that has a value that represents an integer or double.
- Javascript (since ES6) has a "Symbol" type (also know as "Atoms" in other languages, similar to enumeration types).
In PHP the closest thing to this is using a Constant.
The Bash equivalent is declaring a variable readonly with the
-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:
- Variable names should suggest a property or noun. UserName, Width, etc.
- Names should be descriptive, but also concise. Wherever possible, keep variable names to under 3 words or 15 characters but be prepared to sacrifice a few extra characters to improve clarity.
Putting all of this together we get the following syntax diagram:
VariableName ::= ( [$@%&]* ([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
.