From c2a6ad9438465c5de5fa0dd928ebba599ea38ad9 Mon Sep 17 00:00:00 2001 From: Eric McDonald Date: Fri, 27 Dec 2024 11:19:37 -0800 Subject: [PATCH] Copier Template: Development documentation on nomenclature. --- .../sphinx/development/index.rst | 1 + .../sphinx/development/nomenclature.rst | 517 ++++++++++++++++++ .../sphinx/development/releases.rst | 8 +- .../sphinx/development/style.rst.jinja | 30 + template/pyproject.toml.jinja | 1 + 5 files changed, 553 insertions(+), 4 deletions(-) create mode 100644 template/documentation/sphinx/development/nomenclature.rst diff --git a/template/documentation/sphinx/development/index.rst b/template/documentation/sphinx/development/index.rst index da1529f..7ea8796 100644 --- a/template/documentation/sphinx/development/index.rst +++ b/template/documentation/sphinx/development/index.rst @@ -29,6 +29,7 @@ Development environment practices + nomenclature style devapi releases diff --git a/template/documentation/sphinx/development/nomenclature.rst b/template/documentation/sphinx/development/nomenclature.rst new file mode 100644 index 0000000..6b79f28 --- /dev/null +++ b/template/documentation/sphinx/development/nomenclature.rst @@ -0,0 +1,517 @@ +.. vim: set fileencoding=utf-8: +.. -*- coding: utf-8 -*- +.. +--------------------------------------------------------------------------+ + | | + | Licensed under the Apache License, Version 2.0 (the "License"); | + | you may not use this file except in compliance with the License. | + | You may obtain a copy of the License at | + | | + | http://www.apache.org/licenses/LICENSE-2.0 | + | | + | Unless required by applicable law or agreed to in writing, software | + | distributed under the License is distributed on an "AS IS" BASIS, | + | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | + | See the License for the specific language governing permissions and | + | limitations under the License. | + | | + +--------------------------------------------------------------------------+ + + +******************************************************************************* +Nomenclature +******************************************************************************* + +This guide presents naming conventions and patterns for Python and Rust +projects. The lists are not exhaustive, and new patterns may emerge for +specific domains or requirements. + +When working with third-party APIs or established codebases, it may be +appropriate to follow their existing naming conventions rather than those +presented here. The goal is consistency within a given context rather than +rigid adherence to these patterns. + + +Classes +=============================================================================== + +General Guidance +------------------------------------------------------------------------------- + +- Use ``Async`` suffix for asynchronous interfaces. + +- Avoid ``Type`` suffix except when fitting to existing framework. I.e., do not + follow the pattern in Python's ``types`` module unless there is good reason + to do so. + + +Abstract Classes +------------------------------------------------------------------------------- + +- Prefix with ``Abstract`` for abstract base classes. + +- Use adjective names for interface-like classes when they describe + capabilities. + +.. code-block:: python + + class AbstractDictionary: + ''' Abstract base for dictionary types. ''' + + class Comparable: + ''' Interface for objects supporting comparison. ''' + + class Immutable: + ''' Interface for objects preventing modification. ''' + + +Base Classes +------------------------------------------------------------------------------- + +- Use ``Base`` or ``Common`` suffix for base classes. + +- Use ``Extension``/``Supplement`` (Latin-derived) or ``Mixin`` (Germanic-like) + suffix for mix-in classes. + +.. code-block:: python + + class DictionaryBase: + ''' Base class for dictionary implementations. ''' + + class LoggingMixin: + ''' Adds logging capabilities to classes. ''' + + +Container Classes +------------------------------------------------------------------------------- + +Name based on behavior rather than implementation. + +.. code-block:: python + + class ProducerDictionary: + ''' Dictionary producing values on demand. ''' + + class QueueAsync: + ''' Queue with asynchronous interface. ''' + + +Decorator Classes +------------------------------------------------------------------------------- + +- Use adjectives when describing the modification. + +- Use nouns when describing the resulting form. + +.. code-block:: python + + class Comparable: + ''' Decorator class providing comparison capabilities. ''' + + class Dataclass: + ''' Decorator class creating data class. ''' + + +Enum Classes +------------------------------------------------------------------------------- + +- Use plural nouns for enum class names. + +- Use PascalCase for enum members to reflect singleton semantics. + +.. code-block:: python + + class States: + Initial = auto( ) + Execution = auto( ) + Complete = auto( ) + + +Exception Classes +------------------------------------------------------------------------------- + +- Follow standard hierarchy: ``Omniexception`` -> ``Omnierror`` -> specific + exceptions. + +- Use present tense verbs with these patterns: + + - ``[]Failure`` for operation failures + - ``[]Interruption`` for interrupted operations + - ``[]Invalidity`` for invalid states/data + +- Use ``[]Error`` for other error cases. + +.. code-block:: python + + class ConfigureFailure( Omnierror ): + ''' Raised when configuration fails. ''' + + class AttributeInvalidity( Omnierror ): + ''' Raised when attribute value is invalid. ''' + + class ProcessInterruption( Omniexception ): + ''' Raised when process is interrupted. ''' + + +Metaclasses +------------------------------------------------------------------------------- + +- Use ``Class``/``Factory`` (Latin-derived) or ``Builder``/``Maker`` + (Germanic-derived) suffix. + +.. code-block:: python + + class ValidatorClass( type ): + ''' Metaclass for creating validator classes. ''' + + class SetBuilder( type ): + ''' Metaclass for building set classes. ''' + + +Special Purpose Classes +------------------------------------------------------------------------------- + +Use appropriate suffix pairs based on purpose: + +- ``Proxy`` (Latin-derived) or ``Wrapper`` (Germanic-derived) for delegation + patterns +- ``Coordinator``/``Manager``/``Supervisor`` (Latin-derived) or ``Overseer`` + (Germanic-derived) for resource management +- ``Spectator``/``View`` for limited access patterns + +.. code-block:: python + + class WeakrefWrapper: + ''' Wraps object with weak reference semantics. ''' + + class ConnectionManager: + ''' Manages database connections. ''' + + class DictionaryView: + ''' Provides read-only view of dictionary. ''' + + +Functions +=============================================================================== + +General Patterns +------------------------------------------------------------------------------- + +``_``: Where verb describes the action and noun describes the +target. + +``_``: For methods only. Chainable operations typically +returning modified copies. + +Noun Placeholders +------------------------------------------------------------------------------- + +- ````: Named property or field of an object +- ````: Distinct part of a larger system or application +- ````: Boolean predicate or state +- ````: Raw or structured information, regardless of location +- ````: Execution context (process, thread, task) managed by current + process +- ````: Optional functionality that can be enabled/disabled +- ````: Data serialization format (JSON, XML, etc.) +- ````: Planned future execution +- ````: In-process entity (instance of a Python class) +- ````: Callback or event handler +- ````: Claim on future resource usage +- ````: Entity external to the current process (file, network + service, etc.) +- ````: Long-running process or daemon external to current process +- ````: Memory or storage allocation +- ````: Python type or class + +Preposition Prefixes +------------------------------------------------------------------------------- + +- ``as_``: Returns copy of object in different format or type. + Chainable with other methods. + +- ``from_``: Class method that constructs object from specific + format or type. + +- ``with_``: Returns copy of object with modified attributes. + Chainable with other methods. + +Verb Prefixes +------------------------------------------------------------------------------- + +- ``access_``: Returns value via computed or indirect access (e.g., + property getter, descriptor protocol). For in-process objects only. + +- ``acquire_``: Obtains exclusive access to shared resource requiring + explicit release (e.g., mutex, database connection). Antonym: + ``release_``. + +- ``activate_``: Starts execution context or service. For + both in-process executions and external services. Antonym: + ``deactivate_``. + +- ``allocate_``: Reserves system memory or storage space for future use. + Antonym: ``deallocate_``. + +- ``assess_``: Examines data to derive insights or patterns. + +- ``assert_`` [Python]: Verifies resource exists or condition holds, + raising exception if not. [Rust]: Panics if condition fails. Related: + ``verify_`` which returns boolean. + +- ``calculate_``: Computes value from one or more inputs using defined + algorithm. + +- ``cancel_``: Revokes planned execution or resource + claim. Antonym for both ``schedule_`` and ``reserve_``. + See these related patterns for specific usage. + +- ``configure_``: Applies settings or parameters to component, + preparing it for operation. Related: ``prepare_`` for full + initialization. + +- ``create_``: Creates new resource external to current process + (e.g., file, database table). For in-process object creation, see + ``produce_``. Antonym: ``delete_``. + +- ``deactivate_``: Stops execution context or service. + Antonym: ``activate_``. + +- ``deallocate_``: Frees previously allocated system memory or storage + space. Antonym: ``allocate_``. + +- ``delete_``: Removes resource external to current process. + [Python]: For in-process objects, we generally rely on garbage collection or + context managers and do not need explicit destructors. Antonym: + ``create_``. + +- ``deregister_``: Removes previously registered event handler or + callback. Antonym: ``register_``. + +- ``disable_``: Deactivates optional feature or functionality. + Antonym: ``enable_``. + +- ``discover_``: Detects or determines value from environment or + context. + +- ``display_``: Presents data in user-facing format. Synonym: + ``present_``. + +- ``enable_``: Activates optional feature or functionality. Antonym: + ``disable_``. + +- ``ensure_``: Creates resource if it doesn't exist, returns existing + resource if it does. Related: ``create_`` for forced creation. + +- ``examine_``: Retrieves metadata about resource without accessing + full content (e.g., file stats, HTTP HEAD). + +- ``filter_``: Returns subset of objects matching specified criteria. + +- ``intercept_`` [Python]: Invokes functions while capturing their + exceptions for later handling. Used primarily in concurrent execution + contexts where multiple exceptions need collection. + +- ``is_``: Tests type membership or current state. Returns + boolean. Related: ``verify_`` for condition verification. + +- ``modify_``: Updates in-process object state. Alternative to + ``update_`` when context requires disambiguation between in-process + and external modifications. + +- ``parse_``: Extracts structured data from formatted input (e.g., + JSON, XML). + +- ``prepare_``: Fully initializes component, including registration + of handlers/extensions. Related: ``configure_`` for settings + application. + +- ``probe_``: Tests resource accessibility or status. Returns boolean + indicating availability. Related: ``verify_`` for more thorough + verification. + +- ``produce_``: Creates new instance in process memory. For external + resource creation, see ``create_``. + +- ``query_``: Performs structured data retrieval with parameters or + filters. Related: ``retrieve_`` for simpler data access. + +- ``register_``: Adds event handler or callback to registry. Antonym: + ``deregister_``. + +- ``release_``: Releases previously acquired shared resource. + Antonym: ``acquire_``. + +- ``render_