**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