Coding Conventions: Naming and Style guide

Python Style Guide

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.

alllowercase
ALLUPPERCASE
lowerCamelCase
UpperCamelCase
lower_case_with_underscores
UPPER_CASE_WITH_UNDERSCORES
Capitalized_With_Underscores
_LeadingUnderscoreUpperCamelCase
_leadingUnderscoreLowerCamelCase
__LeadingDoubleUnderscoreUpperCamelCase
__leadingDoubleUnderscoreLowerCamelCase

Rules

Python Standard Library methods and attributes

alllowercase startswith() In some cases may be lower_case_with_underscores

Python builtins

alllowercase no underscores setattr()

Vertical Spacing

Spaces between methods and top level functions: two 2

Spaces between Class Definitions: two 2

DocStrings

Triple double quotes. “”” “””

   """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 in 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 style uses indentation to separate sections.

Google style:

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 underscores acronyms should be all uppercase if start uppercase, or all lowercase if start lowercase. http_send Send_HTTP

When using CapCamelCase or mixedCase the acronyms should be treated as words unless the acronym is the last word and then it may be either treated as a word or be in all UPPERCASE httpSend sendHttp sendHTTP

Local Variables and function parameters:

lowerCamelCase.

Any name that conflicts with python reserved word

add trailing underscore: Examples: id_, file_

Package Names:

alllowercase. Pithy and short but evocative.

Module Names

alllowercase. End name in ‘ing’ so can distinquish package and module references when namespacing. First ref is module not package variable such as: core.behaving, core.clustering

Public Module Level Class Instances Singletons

UpperCamelCase

Private Module Level Class Instances Singletons

_LeadingUnderscoreUpperCamelCase

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 or ALLUPPERCASE Not meant to be changed should be numbers or strings. Examples: MY_CONSTANT, SOMECONSTANT

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. Examples: Person BigDogs

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 quantitaive approach to measuring readability in code. It measured error rate in reading and understanding code as a function of style conventions. These include horizontal and veritical white space, line length, varible name length, code block demarcation, etc.

Results were that too much indentation and too little indentation both reduce readability. Ideal is 2, 3, or 4 space indentation. We use 4 because it is the python standard and too hard to fight uphill for the slightly more optimal 3.

Verticle white space matters. Code should have paragraphs. Balanced brackets, indendation and blank lines demarcate paragraphs

For example

void display(void)
{
  int start;

  start = -1;

  if(start == -1)
    return;
}

is more readable than

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

Acronyms which are abbreviations that form pronounceable words may be

highly evocative. radar (RAdio Detecting And Ranging), laser (Light Amplification through Stimulated Emission and Radiation) keri (Key Event Reciept Infrastructure)

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 English suffix composition rules to create pithy terse more consise names that are sufficiently evocative.

Suffix Mapping

Adjective describing module. What does the module enable one to do.

Verb is the deed or act

Object is actor doer

Place to keep track of or create Objects container or factory

doery actorery doerage actorage

of an Doer is a doery or doage or dodom or dohood

-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

Rules for English suffixes

http://www.paulnoll.com/Books/Clear-English/English-suffixes-1.html http://www.prefixsuffix.com/rootchart.php

Suffix Meaning Examples Used

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

er, or, eur agent, one who author, baker, winner, dictator, chauffeur, worker

ed past jumped, baked

ery a place to practice of condition of nunnery, cannery surgery bravery, drudgery

dom state, condition of wisdom, kingdom, martyrdom

ent having the quality of different, dependent, innocent

en made of, to make woolen, wooden, darken

er degree of comparison harder, newer, older

est highest of comparison cleanest, hardest, softest

ful full of graceful, restful, faithful

-hood noun from noun group state of being boyhood, knighthood, womanhood

ible, ile, il capable of being digestible, responsible, docile, civil

ier, ior one who carrier, warrior

ify to make magnify, beautify, falsify

ic like, made of metallic, toxic, poetic

ing action of running, wishing

ion, sion, tion act or state of being confusion, correction, protection

ism fact of being communism, socialism

ish like childish, sheepish, foolish

ist a person who does artist, geologist

ity, ty state of majesty, chastity, humanity

itis inflammation of appendicitis, tonsillitis

ive having nature of attractive, active

ize to make pasteurize, motorize

less without motionless, careless, childless

let small starlet, eaglet

ly like, in a manner 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 noun from noun quality of state of rank of friendship, leadership lordship

-scope instrument for seeing telescope, microscope

-some like tiresome, lonesome

-tude noun from adjective state of altitude, latitude

-ty quality or state of liberty, majesty

-ward toward southward, forward

-y like, full of, diminutive: noisy, sooty, kitty

-ure noun from verb indicating act or office seizure prefecture