diff --git a/docs/naming.md b/docs/naming.md new file mode 100644 index 000000000..fa836f045 --- /dev/null +++ b/docs/naming.md @@ -0,0 +1,389 @@ + +# Python Style Guide for keripy + +The Python PEPs on style have many options or allowed variants. +The purpose of this document is to select a single preferred style +in every case. In general this guide follows PEP-8 but specifies styles +where PEP-8 is silent and varies from PEP-8 in a couple of places namely camelCase +versus underscore_case. The latter (camelCase instead of underscore_case) is +the most violated PEP-8 convention in the Python standard library. +For example the well known logging and unittest packages use camelCase. +Therefore, we are in good company. Because camelCase variables are equally +readable but also more concise than underscore_case_, that improved conciseness +contributes to shorter statement lengths which are themselves more readable. +Readability trumps convention. + +## Indentation + +4 spaces (detab ie no tabs convert tabs to spaces) + +## Naming Convention Labels: +These are used in the rules below. + +*lowercase* +*UPPERCASE* +*lowerCamelCase* +*UpperCamelCase* +*lower_case_with_underscores* +*UPPER_CASE_WITH_UNDERSCORES* +*Capitalized_With_Underscores* +*_LeadingUnderscoreUpperCamelCase* +*_leadingUnderscoreLowerCamelCase* +*__LeadingDoubleUnderscoreUpperCamelCase* +*__leadingDoubleUnderscoreLowerCamelCase* + +## Rules + +### Python Standard Library methods and attributes +*lowercase* or *lower_case_with_underscores* or *lowerCamelCase* depending on package or module. +startswith() +In some cases may be lower_case_with_underscores + +### Python builtins +*lowercase* (no underscores). +setattr() + +### Vertical Spacing +Spaces between methods and top-level functions: + two 2 + +Spaces between Class Definitions: + two 2 + +### DocStrings + Triple double quotes. """ """ + +```python + """If one line doc string then may be all on one line""" + + """If more than one line doc string then first line starts after triple quotes. + Following lines outdent. Embedded strings use 'single quotes'. + """ + + Format for code documentation uses the the Google flavor of sphinx.ext.napolean format. + See + https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html + and + https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google + + The Google Napolean style uses indentation to separate sections. +``` + #### Google style: + +```python +def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True +``` + +### Acronyms +When using *UpperCamelCase* or *lowerCamelCase* the acronyms should be treated as words: + httpSend sendHttp + + +When using underscores, acronyms should be all *lowercase* if start *lowercase*, +or all *UPPERCASE* if start *UPPERCASE*: + http_send Send_HTTP + + +### Local Variables and function parameters: + *lowerCamelCase*. + +### Any name that conflicts with python reserved word + Add trailing underscore: + Examples: id_, file_ + +### Package Names: + *lowercase*. Pithy and short but evocative. + core, test, keri, hio. + +### Module Names + *lowercase*. + End name in 'ing' so can distinguish package and module references + when namespacing. The first ref is module not package variable, such as: + core.behaving, core.clustering + +### Public Module Level Methods and Attributes: + *lowerCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Examples: getName setStyle, display, first, last, itemCount, entities, books, data + +### Private Module Level Methods and Attributes (not exported by from import `*`): + *leadingUnderscoreLowerCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Examples: `_dirtyBit` + +### Constants Module Level: + *UPPER_CASE_WITH_UNDERSCORES* + Not meant to be changed should be numbers or strings. + Examples: MY_CONSTANT + +### Dynamic Global Variables (not constants) Module Level: + *Capitalized_With_Underscores*. + These are reserved for module level globals that may be changed in + multiple places intentionally. + Usually this is bad practice so special syntax is used to indicate + such practice only when necessary. + Examples: Bad_Practice REO_Lat_Lon_NE + +### Exception Classes: + *UpperCamelCase*. + Example: StandardMuxError + +### Class Names: + *UpperCamelCase*. + Classes may be actors which should end in -er or class factories which should end in -ery. + Examples: Employer, Filler, DataFiller, Fillery + +### Public Class Attributes, Class Methods, Static Methods: + *UpperCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Example: TotalInstances, Storage, Store, Redact + +### Private Class Attributes, Class Methods, Static Methods: + *LeadingUnderscoreUpperCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Example: `_TotalInstances _Storage __Entries` + +### Very Private Class Attributes, Class Methods, Static Methods (mangled with class name): + *__LeadingDoubleUnderscoreUpperCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Example: `__TotalInstances __Storage __Entries` + +### Public Instance Methods and Attributes: + *lowerCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Examples: getName setStyle, display, first, last, itemCount, entities, books, data + +### Private Instance and Attributes (not exported with from import `*``): + *leadingUnderscoreLowerCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Examples: `_getScore _setInternal _lastName _count _entries` + + +### Very Private Instance Methods or Attributes (mangled with class name): + *__leadingDoubleUnderscoreLowerCamelCase*. + Methods use verbs. + Attributes that are sequences use plural nouns. + Examples:` __getMyName __displayMoney __creature __secretData __entries` + + + +## Readability + +The book "C Elements of Style" by Qualline used a quantitative approach +to measuring readability in code. It measured the error rate in reading and +understanding code as a function of style conventions. +These include horizontal and vertical white space, +line length, variable name length, code block demarcation, etc. + +One result is that both too much indentation and too little indentation reduce +readability. Ideal indentation is 2, 3, or 4 spaces. We use 4 spaces because it is the +standard for Python, and it would be too hard to fight uphill for the slightly more optimal 3. + +Verticle white space matters. Code should have paragraphs. Balanced brackets, +indentation and blank lines demarcate paragraphs + +For example + +```C +void display(void) +{ + int start; + + start = -1; + + if(start == -1) + return; +} +``` + +is more readable than + +```C +void display(void){ +int start; start = -1; +if(start == -1) return; +} +``` + +Line length matters. Which means variable length matters. +Simple logic statments that wrap are no longer simple. +Context may provide meaning. Use doc strings to establish context. +Scope and class Nesting may provide meaning. + +Shorter evocative names are more readable than long descriptive names when +composing code because the long names make the statements that use the variables +too long to be easily readable. + +`aviary` vs. `flyingBirdCage` + +`aviary.bird` vs. `flyingBirdCage.bird` + +`hawk.wing.size` vs. `hawkWingSize` + + +## Evocative Semantic Naming + +evocative -adjective tending to evoke: + The perfume was evocative of spring. + +evoke -verb (used with object), + to call up or produce (memories, feelings, etc.): + to evoke a memory. + to elicit or draw forth: + His comment evoked protests from the shocked listener + +An evocative semanitic name is a name that calls up the meaning without having +to explicity detail the meaning. Its a type of mneumonic that balances semantics +with conciseness which balance improves overall readability and understanding. + +*aviary* vs *flyingBirdCage* + +Use the doc string for a method, or a function, or a module to establish +the semantic meaning of the names used within that context. +The doc string can be verbose, which enables the names to be terse. The doc string only +appears once in the code, whereas the names may appear many times in the code. +The terse names need be merely sufficiently evocative to remind a reader of the semantic context +established by the doc string. As a result, the statements are shorter and hence more readable. +This optimizes the overall readability of the code. + +### Acronyms +Acronyms are abbreviations that form pronounceable words. These may be highly evocative. +`radar` (RAdio Detecting And Ranging), +`laser` (Light Amplification through Stimulated Emission and Radiation) +`keri` (Key Event Reciept Infrastructure) + + +## Suffix Mapping + +Use English suffix composition rules to create pithy terse more consise names +that are sufficiently evocative. Can use suffix rules to create derivative words +that are evocative and terse. Words don't have to be in the English +dictionary or in one's spelling dictiony to be valid, understandable terms. +The suffixing rules of English apply nonetheless. Many dictionary words +started as bespoke created words using suffixing rules that through common +use become dictionary words. Because code if a very narrow highly technical +context it is ok to maximize readabilty by using evocative made-up non-dictionary +terms derived from applying suffixing rules. + + +For example, one can use suffix rules for `ing` to create verb derived +from root word that is self-descriptive as a module name of the activity performed by module's code. The +module name is a passive verb that describes the main purpose of the module. For example, +`testing` from `test` or `logging` from `log`. +Answer the question, "What does the module enable one to do as verb ending in `ing`?". + +Method names are active verbs like `log` or `delete`. +Object names are nouns that imply an actor or doer. +Use suffix rules to form action noun like 'logger'. +Objects that manage other objects are place nouns that imply an activity like `factory`. + nunnery, brewery, doery + For a Doer we could have doery, doage, dodom, doship, dohood. +A variable or attribute whose value describes a property or potential like deletable or deletive. + +### More common suffix rules: + +-er -or -eur -ster Agent one who does something brewer (Object Classes) +-ery a place for an actor to act factory brewery (Object Factories) +-ing action of running, wishing (Module Names) +-age state of acting actor to act brewerage +-dom state of doing acting kingdom +-hood state of being childhood +-ship quality of or state of rank of midship +-ize to make itemize +-izer Someone who makes one do itemizer +-ive having nature of active rotative inceptive +-acy -isy -ty quality of linty piracy clerisy +-ion -tion -sion act or state of action itemization +-y -ly like full of happening noisy monthly + +patron +patroner +patronist +patronery +patronage +patrondom +patronship +patronacy +patronhood +patronize +patronish +patronive +patronlet +patronly +patrony + + + + + +### Suffixes +-able, -ible: capable of: worthy, agreeable, comfortable, credible. +-age: act of or state of: salvage, bondage. +-acy, -isy: quality: hypocrisy, piracy. +-al, -eal, -ial: on account of related to, action of: judicial, official arrival, refusal. +-ance, -ence: act or fact of doing state of: violence, dependence allowance, insurance. +-ant: quality of one who: defiant, expectant, reliant occupant, accountant. +-dom: state, condition of: wisdom, kingdom, martyrdom. +-er, -or, -eur: agent, one who: author, baker, winner, dictator, chauffeur, worker. +-ier, -ior: one who: carrier, warrior. +-ist: a person who does: artist, geologist. +-er: degree of comparison: harder, newer, older. +-est: highest degree of comparison: hardest, newest, oldest. +-ed: past: jumped, baked. +-ery: a place to practice of condition of: nunnery, cannery surgery bravery, drudgery. +-ent: having the quality of: different, dependent, innocent. +-en: made of, to make: woolen, wooden, darken. +-ful: full of: graceful, restful, faithful. +-hood: state of being: boyhood, knighthood, womanhood. +-ible, -ile, -il: capable of being: digestible, responsible, docile, civil. +-ify: to make: magnify, beautify, falsify. +-ic: like, made of: metallic, toxic, poetic. +-ing: action of: running, wishing. +-ion: act or state of: confusion, correction, protection. +-ism: fact of being: communism, socialism, defeatism. +-ish: like: childish, sheepish, foolish. +-ity, -ty: state of: security, majesty, chastity, humanity. +-itis: inflammation of: appendicitis, tonsillitis. +-ive: having nature of: attractive, active. +-ize: to make: pasteurize, motorize. +-less: without: keyless, motionless, careless, childless. +-let: small: starlet, eaglet. +-ly: like, in a manner of, happening: heavenly, remarkably, suddenly every absolutely, monthly. +-ment: state or quality, act of doing: accomplishment, excitement placement, movement. +-meter: device for measuring: thermometer, barometer. +-ness: state of: blindness, kindness. +-ology: study of: geology, zoology, archaeology. +-ous, -ious: full of: joyous, marvelous, furious. +-ship: quality of, state of, rank of: friendship, leadership lordship +-scope: instrument for seeing: telescope, microscope. +-some: like: tiresome, lonesome. +-tion, -sion: action, state of being: condition, attention, fusion. +-ty quality or state of: liberty, majesty. +-ward: direction: toward southward, forward. +-y: like, full of, diminutive: noisy, sooty, kitty. +-ure: noun from verb indicating act or office: seizure prefecture. + +### References +https://www.amazon.com/Elements-Style-Programmers-Elegant-Programs/dp/1558512918/ref=sr_1_1?crid=1G1NI85WG4JIP&keywords=c+elements+of+style&qid=1700001994&sprefix=c+elements+of+style+%2Caps%2C122&sr=8-1 +http://www.paulnoll.com/Books/Clear-English/English-suffixes-1.html +http://www.prefixsuffix.com/rootchart.php