**Etymological programing** is a set of conventions used by site.author to use a //[couple thousand|docs]// different functions ==fluently==. By writing this document site.author hopes to gather the conventions in a single place, so they can mature.
## Vision and scope
**Etymological programing** deals chiefly with the ==naming of functions and variables==, by analogy with the //naming of words// in every world language.
The ultimate goal is to save cognitive effort and thus increase the power and joy of bringing ideas to life, especially for //small groups of programmers creating small codebases// (below 100k lines or 10k functions).
At a basic level, **Etymological programing** entails knowing ==return and argument types== plus ==argument positions== just by reading the //function name//. At an intermediate level it means quickly ==finding the right function== even after //forgetting its name// or immediately check whether such a function //already exists//. At an advanced level it could mean ==understanding an unknown function== based on its name alone, //before peeking at the documentation or source code, if at all//.
When adding new [#aspects of **Etymological programing**], one should be guided by the question: //what feels more natural?// Let's bring the //language// back into the //programming language//!
## Aspects of Etymological programming
### Naming functions
####Capitalised
Functions are always *Capitalised* and *CamelCased* //even when used as variables//. No other variable type may be capitalised.
#### Last Word
The last word in a function always identifies its return type.
##### Side effects
Shall a function not return anything (only produce a side effect) the last word must be a verb instead, without any suffix added.
#### Word and argument order
The order and name of all words in a function, except the [#last word], matches the order and name of all argument variables.
##### Reordering arguments and function name words
Whenever arguments are reordered, all words in a function name must be reordered accordingly. A //find and replace tool// is essential.
Reordering should occur whenever it would result in having less words, by allowing [#grouping] and//or by [#omitting].
##### Grouping function words
Shall several arguments have the exact same name, instead of repeating them, a [#repetition numeral prefix] is applied.
##### Omitting
When the last argument name coincides with the name of the return variable, one of them can be simply omitted.
| **Idea** omitting it could cause ambiguity, maybe a suffix could be appended to resolve? Also, what happens to the return type when omitting and grouping are combined?
### Type capitals
[#Type capitals] can be used to name variables that take a precise type, where no more specific name would be appropriate. They arise as arguments of low-level function libraries.
CAPITAL TYPE
A array
D boolean (dual)
F function
G graph
N number
O object
R regex
S string
U url
Type capitals are UPPERCASE and may be [#combined].
| **Idea** uniformise type abbreviations and single type suffixes
#### Combining type capitals
Arguments of an //overloaded// function can have multiple types. This is expressed concisely by concatenating type capitals. For instance, one could define a function ´´Length(SAO)´´ which would calculate the lengths of a //string// ´´S´´ (number of characters) or an //array// ´´A´´ (number of entries) or an //object// ´´O´´(number of keys).
### Type suffixes
[#Type suffixes] identify variable types concisely and can be appended to any chosen name.
For example, let's assign this //glyph//: :music: to a variable named ´´glyph´´. Then ´´glyphs´´ would be an array ´´[♫, ♫, ♫]´´, whereas ´´glypht´´ would be a textual representation such as ´´"music"´´ , and ´´glyphed´´ would be ´´true´´ or ´´false´´ (a boolean) depending on whether something is a //glyph//.
There are [#single type] suffixes, as well [#Multi-type] suffixes.
#### Single type
SUFFIX MEANING MNEMONIC
a array *a* is the first letter of //array//
s array of *-s* forms a plural in English, naturally meaning a collection of items
o object *o* is the first letter of //object//
v dictionary whose values of *v* is the first letter of //values//
k dictionary whose keys of *k* is the first letter of //key//
ed boolean value *-ed* forms a past participle, implying the result of a concluded action
n number/name *n* is the first letter of //number// (and of //name//)
t text (string) *t* is the first letter of //text//
l html/xml (as text) *l* is the last letter of //html//
el html node (as element) *el* is at the begining of //element//
g graph *g* is the first letter of //graph//
u url *u* is the first letter of //url//
ev event object *ev* is the beginning of //event//
Letter //e// should never be used as a prefix, because it is already a part of other prefixes, and because it can be used to as [#linking] element.
#### Multi-type suffixes
Multi-type suffixes are convenient when naming arguments of conveniently overloaded functions.
SUFFIX MEANING MNEMONIC
i item or array thereof *i* is the first letter of "item", but also a plural in Italian
j item or object thereof *j* is similar to i
u item or undefined *u* is the first letter of "undefined"
x item or text thereof *x* is text but could be something else
yr item or function that returns it see [#function suffix cascade]
#### Silent suffix
SUFFIX MEANING MNEMONIC
h not an argument *h* a silent letter in many languages
#### Conversion suffixes
These represent a transformation
SUFFIX MEANING MNEMONIC
z item out of array thereof mirror of *s*
#### Function suffix cascade
This cascade is useful when naming functions that return other functions, several levels deep. Typical uses arise in //currying//, //function factories// and //callback pyramids//.
The letter *-r* was chosen because this is strongly associated with verbs in Latin languages like French and Spanish.
SUFFIX DEPTH RETURN TYPE
ar 0 item (could be a function)
er 1 function, that returns an item
ir 2 function, that returns a function, that returns an item
or 3 function, that returns a function, that returns a function, that returns an item
By consistently naming all functions with a specific return type, suffix *-ar* need never be used, except internally. Indeed, if one wishes to emphasise that a return type is indeed not a function, then suffixing *-ar* is advised.
In practice, ==suffixes *-er* is the most used== and *-ir* surfaces occasionally. Suffix *-or* may signal unnecessary complexity, which defeats the [#vision of *etymological programming*].
### Suffix nesting
Nesting suffixes creates a ==possessive== relation. So ´´texts´´ means an //array// (-s) containing items of type //text//, ´´textsv´´ means an dictionary (-v) containing in each value a //texts// array. Conversely, ´´textvs´´ means an array of dictionaries, each containing in each value one //text// item.
With deeper nesting, words will be harder to pronounce. This can signal unnecessary complexity, but occasionally may be useful. Enter the [#linking e].
#### Linking e
As another example, ´´textses´´ means an //array// containing another //array// containing //text//. Here a [#linking e] was added to help pronounciation, even though ´´textss´´ would be valid.
### Prefixes
#### Common Prefixes
PREFIX MEANING EXAMPLE CLARIFICATION
Pre Before, beginning ´´PrefixString´´ prepends to start of string
Pos After, ending ´´PosfixString´´ appends to end of string
Un Contrary or complementary ´´UnPrefixString´´ removes from start of string
Ex Outside ´´ExfixString´´ adds to the outside (both ends of string)
In Inside ´´UnInfixString´´ removes from inside (not at the ends)
Re Enforce ´´ReString(AFNO)´´ coerces arrays, functions, numbers objects, into strings
Dis Distinct ´´DisArray(A)´´ deduplicates all items in an array
| **Idea** uniform letter immediately after prefix - is it always capital?
#### Argument number prefixes (latins)
These prefixes specify a repeated number of arguments of the same type.
PREFIX NUMBER USAGE
si 1 probably not needed
bi 2 common
ter 3 rare
qua 4 rare
qui 5 (impractical)
sen 6 ''
sep 7 ''
oct 8 ''
nov 9 ''
den 10 ''
... ... ...
pluri many variable number of arguments (could be as low as zero)
Obs: *bi-* and *si-* are shorthands for //bin-// and //sin-//, the actual distributive latin numeral prefixes.
#### Standalone Prefixes
Actually, ´´Un´´ can also be used as a standalone function, e.g. ´´Un(Arrayed)´´ creates a new function that checks whether an item is //not an array//.
| **Idea** shouldn't Un be named Uner? Also does this idea generalise to other prefixes?
#### Free numeral prefixes (greeks)
These prefixes may be used freely, but never to refer to the number of arguments.
PREFIX NUMBER
mono 1
di 2
tri 3
tetra 4
penta 5
hexa 6
hepta 7
octa 8
ennea 9
deca 10
... ...
poly many
####References
All greek and latin prefixes [A-H|https://en.wikipedia.org/wiki/List_of_Greek_and_Latin_roots_in_English/A%E2%80%93G],[H-O|https://en.wikipedia.org/wiki/List_of_Greek_and_Latin_roots_in_English/H%E2%80%93O] and [P-Z|https://en.wikipedia.org/wiki/List_of_Greek_and_Latin_roots_in_English/P%E2%80%93Z]
Numeral Prefixes [https://en.wikipedia.org/wiki/Numeral_prefix]
${
// a work in progress
///////////////////////////////////////////////////////////////////////////////
//
// Function Naming conventions
//
// 1.0)the last word reveals the return type:
// - "F", "Fun" : a function
// - "A","Array" : an array
// - "N","Number" : a number
// - "O","Object", "Obj" : an object
// - "S","String" : a string
//
// - "Selector" : a text selector for queryselector matching (ids don't require #)
// - "Html" : a string of HTML code
// - "Node" : a node element (live HTML)
// - "Nodex" : "Node" or "HTML"
// - "Elsel" : "Node" or "Selector"
// - "Element" : a Node or HTML code or a Selector (overloaded)
//
// - any verb : side effects (optionally return a "pass"/"fail" boolean)
// - "Draw" : Draws something on the screen (side-effect)
//
// - any adjective : binary value (true/false)
//
// - "Opts" : shallow Object, containing options
//
// 1.1)Suffixes added to a root type
// - "-a" : an array
// - "-s" : an array of (containing as items)
// - "-i" : either a single item or an array of root items
// - "-o" : an object
// - "-z" : a dictionary of (containing as values)
// - "-n" : a name/key (with reference to a dictionary)
//
// - "-l" : html (as text)
// - "-el" : node element
// - "-ex" : either a single item or a stringified version of the item
// - "-ev" : an event
//
// - "-ed" : binary, possibly related to the root item
//
// - "-er", : a function - 1x deep
// - "-ir" : a function, that returns a function - 2x deep
// - "-or" : a function, that returns a function - 3x deep
// - "-ur" : a function, that returns a function - 4x deep
// - "-yr" : a function, that returns a function - 5x deep
// - "-ar" : any (need not return a function) - 0x deep (internal use only)
//
// 1.2) Combining multiple types in arguments (type overloading)
// - "AO", : Array or Object
// - "SAO" : Array, Object or String
// - "ANOS" : Array, Object, Number or String
// - "AFNOS" : Function, Array, Object, Number or String
// - ...
//
// 2) Prefixes (as in spoken language):
// -"Un-" : returns the Symmetric / Complementary value
// -"Re-" : enforces/coerces/compels a particular type or format
// -"Pre-" : at beginning / before
// -"Pos-" : at the end / after
// -"Supra-" : above, e.g. in an hierarchy
// -"Sub-"/"Infra-" : below
// -"Ex-" : outside
// -"In-" : inside
// -"Accu-" : accumulated
// -"Dis-" : distinct
// -"Dis-" : distinct
//
// 3) "Input1Input2...Output" (self-describing) names are preferred. For instance "FirstSecond...Type" receives those "First","Second",... as arguments and returns "Type"
//
// 4) the first word may also refer to a particular set of related functions
//
// 5) Forbidden names: anything vague, such as: "data" (TODO)
//
// 6) function names are Capitalised (and camel-cased):
// - avoids conflicts with most JS libraries
// - feels natural
// - marks functions as distinct from other variable types
// 6.1) common acronyms are Capitalised as normal words, e.g. Html, Rss, Css,...
""
}
// ## Principles
// PRINCIPLE MEANING IMPLICATIONS
// Humanable code should be readable by humans, as is code cannot be obfuscated nor minified
// Atomic code should be divided in its smallest meaningful components all functions are short, and become modular
// Literate the meaning of each piece of code should be obvious to any reader the name of each function fully describes its behaviour; unit tests are appended to each function code