Create ADR for Naming Conventions

[Polichinel]

Create ADR for Naming Conventions of Classes and Functions

Description:
Develop an Architectural Decision Record (ADR) to document the standard naming conventions for all classes, functions, variables, and files in the package. This ADR should establish flexible, well-defined guidelines that enhance readability, maintainability, and adherence to Python and MLOps best practices while allowing some adaptability for evolving project needs.

The ADR must also be consistent with the md&d_python_style_guide, ensuring alignment across all documentation and coding standards.

Guidelines and Examples

• Class Naming:

  • Use PascalCase for class names.
  • Ensure class names are descriptive yet concise, conveying each class’s purpose without verbosity. This structure supports modularity and makes the codebase easy to navigate.
  • Examples:
    • Utility Classes (Utils): For general-purpose helper functions that don’t fit within a specific module (e.g., DataUtils, FileUtils).
    • Handler Classes (Handler): For managing specific processes or workflows, especially useful in data handling or API interactions (e.g., DataHandler, RequestHandler).
    • Manager Classes (Manager): For classes that coordinate actions among multiple modules or components, aligning with DevOps' modular design principles (e.g., SessionManager, PipelineManager).
    • Loader Classes (Loader): For classes dedicated to loading data, configurations, or assets, commonly used in data pipelines (e.g., DataLoader, ConfigLoader).
    • Builder Classes (Builder): For constructing or configuring objects, aligning with standard MLOps practices of creating reusable and testable components (e.g., ModelBuilder, PipelineBuilder).

• Function and Variable Naming:

  • Use snake_case for function and variable names, following Python’s conventions for readability and consistency.
  • Function names should be verb-based, clearly indicating the function’s primary action. Clarity in function names is crucial for tracking processes and ensuring smooth CI/CD operations.
  • Examples:
    • Public Functions: Use descriptive, action-based names to clarify their purpose (e.g., load_data, save_results, evaluate_model).
    • Private Functions: Prefix with an underscore to signal intended internal use, supporting encapsulation (e.g., _validate_input, _load_config).
    • Constants: Use uppercase with underscores for global constants to clearly differentiate them from mutable variables (e.g., DEFAULT_BATCH_SIZE, MAX_RETRY_COUNT).

• File Naming:

  • Use lowercase with underscores for file names.
  • Ensure file names are descriptive and specific to the content or function of the file, aiding rapid identification in larger repositories. Align with DevOps best practices for clear organization within the project structure.
  • Examples: data_loader.py, config_handler.py, model_evaluator.py.

• Special Cases:

  • Document any exceptions or domain-specific naming needs. For example, abbreviations like cfg for configuration files or meta for metadata can be acceptable if consistently applied. Consider the need for such exceptions to fit within MLOps principles of reusability and clarity.

Objective:
To establish a consistent yet adaptable naming convention that supports readability, maintainability, and scalability, in line with MLOps best practices and the md&d_python_style_guide.

Tasks:

• Review Python and MLOps best practices for naming conventions.
• Draft the ADR, presenting these guidelines with examples, and noting alignment with the md&d_python_style_guide.
• Conduct a review with at least two team members to gather input and confirm alignment with the project’s style requirements.
• Finalize and publish the ADR in the project documentation, ensuring it is accessible and referenced as a standard.

Labels: documentation, ADR, enhancement