> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Naming Conventions

> This document establishes naming conventions for the myspellchecker codebase to ensure consistency and clarity.

Consistent names make the codebase easier to navigate and reduce cognitive load for contributors. Follow these patterns for methods, classes, variables, files, and docstrings.

## Method Naming Patterns

### Public API Methods

| Pattern      | Purpose                                  | Example                                      |
| ------------ | ---------------------------------------- | -------------------------------------------- |
| `check_*`    | Public entry points for spell checking   | `check()`, `check_batch()`, `check_async()`  |
| `validate_*` | Internal validation methods              | `validate()`, `validate_sentence()`          |
| `get_*`      | Data retrieval methods                   | `get_syllable_frequency()`, `get_word_pos()` |
| `is_*`       | Boolean validation checks                | `is_valid_syllable()`, `is_valid_word()`     |
| `has_*`      | Existence checks (dictionary membership) | `has_syllable()`, `has_word()`               |
| `create_*`   | Factory methods                          | `create_default()`, `create_fast()`          |
| `build_*`    | Builder pattern methods                  | `build()`, `build_from_corpus()`             |

### Distinction: `is_*` vs `has_*`

* **`is_valid_*()`**: May perform validation beyond existence check (e.g., rule validation)
* **`has_*()`**: Pure existence check - only tests dictionary membership

```python theme={null}
# is_valid_syllable may check orthographic rules + dictionary
provider.is_valid_syllable("မြန်")  # True if valid Myanmar syllable AND in dictionary

# has_syllable only checks dictionary membership
provider.has_syllable("မြន်")  # True if in dictionary, regardless of orthographic validity
```

### Distinction: `check_*` vs `validate_*`

* **`check_*()`**: High-level public API (returns `Response` objects)
* **`validate_*()`**: Lower-level internal methods (returns `List[Error]`)

```python theme={null}
# Public API - full spell checking pipeline
result = checker.check("မြန်မာ")  # Returns Response with errors, suggestions, metadata

# Internal - validation only
errors = validator.validate("မြန်မာ")  # Returns List[Error]
```

## Class Naming Patterns

| Pattern      | Purpose                          | Example                                                  |
| ------------ | -------------------------------- | -------------------------------------------------------- |
| `*Validator` | Validation logic                 | `SyllableValidator`, `WordValidator`, `ContextValidator` |
| `*Provider`  | Data access abstraction          | `DictionaryProvider`, `SQLiteProvider`                   |
| `*Checker`   | Analysis/checking components     | `NgramContextChecker`, `SemanticChecker`                 |
| `*Factory`   | Object creation                  | `ComponentFactory`, `POSTaggerFactory`                   |
| `*Config`    | Configuration classes            | `SpellCheckerConfig`, `SymSpellConfig`                   |
| `*Strategy`  | Strategy pattern implementations | `ValidationStrategy`, `ToneValidationStrategy`           |
| `*Error`     | Error types                      | `SyllableError`, `WordError`, `ContextError`             |

## Variable Naming

### General Rules

1. Use `snake_case` for variables and functions
2. Use `PascalCase` for classes
3. Use `UPPER_SNAKE_CASE` for constants
4. Use descriptive names that indicate purpose

### Specific Patterns

| Context         | Pattern                     | Example                                      |
| --------------- | --------------------------- | -------------------------------------------- |
| Syllable data   | `syllable_*`                | `syllable_frequency`, `syllable_cache`       |
| Word data       | `word_*`                    | `word_frequency`, `word_errors`              |
| Configuration   | `*_config`                  | `symspell_config`, `ngram_config`            |
| Cache instances | `*_cache`                   | `syllable_cache`, `bigram_cache`             |
| Thresholds      | `*_threshold`               | `bigram_threshold`, `confidence_threshold`   |
| Counts/sizes    | `*_count`, `*_size`         | `syllable_count`, `cache_size`               |
| Flags           | `use_*`, `enable_*`, `is_*` | `use_phonetic`, `enable_caching`, `is_valid` |

### Avoid Ambiguous Names

| Avoid    | Prefer                                | Reason            |
| -------- | ------------------------------------- | ----------------- |
| `data`   | `syllable_data`, `word_frequencies`   | Too generic       |
| `result` | `validation_result`, `check_response` | Unclear what type |
| `temp`   | `cached_value`, `intermediate_score`  | Non-descriptive   |
| `val`    | `value`, `syllable_value`             | Abbreviated       |
| `idx`    | `index`, `word_index`                 | Abbreviated       |
| `cb`     | `callback`, `on_complete`             | Abbreviated       |

## Private Method Naming

Use single underscore prefix for all private methods:

```python theme={null}
class SpellChecker:
    def check(self, text):        # Public
        self._validate(text)       # Private
        self._build_response()     # Private

    def _validate(self, text):     # Single underscore - private
        pass

    def _build_response(self):     # Single underscore - private
        pass
```

**Do NOT use double underscore** except for Python name mangling requirements:

```python theme={null}
# Avoid
def __compute_score(self):  # Double underscore - unnecessary

# Prefer
def _compute_score(self):   # Single underscore - standard private
```

## Parameter Naming

### Boolean Parameters

Use positive names that indicate the enabled state:

```python theme={null}
# Good
def check(text, use_context_checker=True, enable_suggestions=True):
    pass

# Avoid
def check(text, disable_context=False, no_suggestions=False):
    pass
```

### Configuration Parameters

Match the configuration class field names:

```python theme={null}
# Config class
class SymSpellConfig:
    prefix_length: int = 10
    beam_width: int = 50

# Method parameters should match
def create_symspell(prefix_length=10, beam_width=50):
    pass
```

## File Naming

| Type        | Pattern                         | Example                                |
| ----------- | ------------------------------- | -------------------------------------- |
| Module      | `snake_case.py`                 | `spell_checker.py`, `ngram_context.py` |
| Test file   | `test_*.py`                     | `test_spell_checker.py`                |
| Config file | `*_config.py` or `*_configs.py` | `algorithm_configs.py`                 |
| Interface   | `interfaces.py` or `base.py`    | `providers/base.py`                    |
| Constants   | `constants.py`                  | `training/constants.py`                |

## Docstring Conventions

Follow Google-style docstrings:

```python theme={null}
def get_syllable_frequency(self, syllable: str) -> int:
    """
    Get corpus frequency count for a syllable.

    Args:
        syllable: Myanmar syllable (Unicode string) to look up.

    Returns:
        Integer frequency count. Returns 0 if syllable not found.

    Raises:
        ValueError: If syllable is empty string.

    Example:
        >>> provider.get_syllable_frequency("မြန်")
        15432
    """
    pass
```

### Return Type Documentation

For complex return types, document the structure:

```python theme={null}
def analyze(self, text: str) -> Tuple[List[Error], Dict[str, Any]]:
    """
    Analyze text for spelling errors.

    Returns:
        Tuple containing:
            - errors (List[Error]): List of detected errors
            - metadata (Dict[str, Any]): Analysis metadata with keys:
                - "processing_time" (float): Time in seconds
                - "word_count" (int): Number of words analyzed
                - "error_rate" (float): Errors per word ratio
    """
    pass
```