diff options
Diffstat (limited to 'doc/nep1.rst')
| -rw-r--r-- | doc/nep1.rst | 76 |
1 files changed, 75 insertions, 1 deletions
diff --git a/doc/nep1.rst b/doc/nep1.rst index c4d445681..1ef8c3c24 100644 --- a/doc/nep1.rst +++ b/doc/nep1.rst @@ -60,7 +60,7 @@ Spacing and Whitespace Conventions Naming Conventions -------------------------- +------------------ Note: While the rules outlined below are the *current* naming conventions, these conventions have not always been in place. Previously, the naming @@ -147,6 +147,80 @@ changed in the future. an in-place version should get an ``-In`` suffix (``replaceIn`` for this example). +The stdlib API is designed to be **easy to use** and consistent. Ease of use is +measured by the number of calls to achieve a concrete high level action. The +ultimate goal is that the programmer can *guess* a name. + +The library uses a simple naming scheme that makes use of common abbreviations +to keep the names short but meaningful. + + +------------------- ------------ -------------------------------------- +English word To use Notes +------------------- ------------ -------------------------------------- +initialize initT ``init`` is used to create a + value type ``T`` +new newP ``new`` is used to create a + reference type ``P`` +find find should return the position where + something was found; for a bool result + use ``contains`` +contains contains often short for ``find() >= 0`` +append add use ``add`` instead of ``append`` +compare cmp should return an int with the + ``< 0`` ``== 0`` or ``> 0`` semantics; + for a bool result use ``sameXYZ`` +put put, ``[]=`` consider overloading ``[]=`` for put +get get, ``[]`` consider overloading ``[]`` for get; + consider to not use ``get`` as a + prefix: ``len`` instead of ``getLen`` +length len also used for *number of elements* +size size, len size should refer to a byte size +capacity cap +memory mem implies a low-level operation +items items default iterator over a collection +pairs pairs iterator over (key, value) pairs +delete delete, del del is supposed to be faster than + delete, because it does not keep + the order; delete keeps the order +remove delete, del inconsistent right now +include incl +exclude excl +command cmd +execute exec +environment env +variable var +value value, val val is preferred, inconsistent right + now +executable exe +directory dir +path path path is the string "/usr/bin" (for + example), dir is the content of + "/usr/bin"; inconsistent right now +extension ext +separator sep +column col, column col is preferred, inconsistent right + now +application app +configuration cfg +message msg +argument arg +object obj +parameter param +operator opr +procedure proc +function func +coordinate coord +rectangle rect +point point +symbol sym +literal lit +string str +identifier ident +indentation indent +------------------- ------------ -------------------------------------- + + Coding Conventions ------------------ |