cognitive/docs/guides/naming_conventions.md

# Naming Conventions Guide

---
title: Naming Conventions Guide
type: guide
status: stable
created: 2024-02-06
tags:
  - conventions
  - naming
  - standards
  - organization
semantic_relations:
  - type: implements
    links: [[documentation_standards]]
  - type: relates
    links:
      - [[knowledge_organization]]
      - [[ai_file_organization]]
---

## Overview

This guide establishes comprehensive naming conventions for all components in our cognitive modeling framework, ensuring consistency and clarity across documentation, code, and resources.

## File Naming

### 1. Documentation Files
```python
# @doc_file_patterns
doc_patterns = {
    "concepts": {
        "pattern": "{concept_name}.md",
        "example": "active_inference.md",
        "rules": {
            "lowercase": True,
            "separators": "_",
            "max_length": 50
        }
    },
    "guides": {
        "pattern": "{category}_{topic}.md",
        "example": "ai_documentation_style.md",
        "rules": {
            "category_prefix": True,
            "descriptive_name": True
        }
    },
    "templates": {
        "pattern": "{type}_template.md",
        "example": "concept_template.md",
        "rules": {
            "template_suffix": True,
            "type_prefix": True
        }
    }
}
```

### 2. Code Files
```python
# @code_file_patterns
code_patterns = {
    "implementation": {
        "pattern": "{module}_{component}.py",
        "example": "belief_updater.py",
        "rules": {
            "lowercase": True,
            "descriptive": True,
            "max_length": 40
        }
    },
    "tests": {
        "pattern": "test_{module}_{feature}.py",
        "example": "test_belief_updating.py",
        "rules": {
            "test_prefix": True,
            "match_implementation": True
        }
    },
    "utilities": {
        "pattern": "{category}_utils.py",
        "example": "matrix_utils.py",
        "rules": {
            "utils_suffix": True,
            "category_prefix": True
        }
    }
}
```

## Component Naming

### 1. Class Names
See [[code_organization]] for implementation context.

```python
# @class_patterns
class_patterns = {
    "agents": {
        "pattern": "{Type}Agent",
        "example": "ActiveInferenceAgent",
        "rules": {
            "PascalCase": True,
            "descriptive_prefix": True,
            "agent_suffix": True
        }
    },
    "models": {
        "pattern": "{Type}Model",
        "example": "BeliefModel",
        "rules": {
            "PascalCase": True,
            "model_suffix": True
        }
    },
    "components": {
        "pattern": "{Role}{Type}",
        "example": "BeliefUpdater",
        "rules": {
            "PascalCase": True,
            "role_prefix": True
        }
    }
}
```

### 2. Method Names
```python
# @method_patterns
method_patterns = {
    "actions": {
        "pattern": "{verb}_{object}",
        "example": "update_beliefs",
        "rules": {
            "snake_case": True,
            "verb_first": True
        }
    },
    "properties": {
        "pattern": "{object}_{attribute}",
        "example": "belief_state",
        "rules": {
            "snake_case": True,
            "noun_first": True
        }
    },
    "callbacks": {
        "pattern": "on_{event}",
        "example": "on_belief_update",
        "rules": {
            "on_prefix": True,
            "event_focus": True
        }
    }
}
```

## Documentation Structure

### 1. Section Headers
```python
# @section_patterns
section_patterns = {
    "main_sections": {
        "pattern": "## {Category}",
        "example": "## Overview",
        "rules": {
            "title_case": True,
            "max_words": 3
        }
    },
    "subsections": {
        "pattern": "### {Number}. {Title}",
        "example": "### 1. Implementation Details",
        "rules": {
            "numbered": True,
            "title_case": True
        }
    }
}
```

### 2. Link References
See [[linking_patterns]] for detailed linking guidelines.

```python
# @link_patterns
link_patterns = {
    "internal": {
        "pattern": "[[{category}/{name}]]",
        "example": "[[concepts/active_inference]]",
        "rules": {
            "category_prefix": True,
            "lowercase_path": True
        }
    },
    "aliased": {
        "pattern": "[[{path}|{display}]]",
        "example": "[[active_inference|Active Inference]]",
        "rules": {
            "descriptive_alias": True,
            "consistent_display": True
        }
    }
}
```

## Metadata Conventions

### 1. YAML Frontmatter
```yaml
# @frontmatter_patterns
frontmatter:
  title:
    pattern: "{Type}: {Description}"
    example: "Guide: Active Inference Implementation"
    rules:
      - title_case: true
      - max_length: 60
  
  tags:
    pattern: ["{category}", "{subcategory}", "{specific}"]
    example: ["implementation", "active-inference", "agent"]
    rules:
      - lowercase: true
      - hyphen_separator: true
  
  semantic_relations:
    pattern:
      type: "{relationship_type}"
      links: ["[[{target}]]"]
    example:
      type: "implements"
      links: ["[[active_inference]]"]
```

### 2. Code Documentation
```python
# @docstring_patterns
docstring_patterns = {
    "class": {
        "pattern": """
        {Description}
        
        See [[{concept}]] for theoretical background.
        
        Attributes:
            {name} ({type}): {description}
        """,
        "rules": {
            "theoretical_link": True,
            "attribute_docs": True
        }
    },
    "method": {
        "pattern": """
        {Description}
        
        See [[{implementation}]] for details.
        
        Args:
            {name} ({type}): {description}
        
        Returns:
            {type}: {description}
        """,
        "rules": {
            "implementation_link": True,
            "complete_signature": True
        }
    }
}
```

## Validation Rules

### 1. Naming Validation
```python
# @validation_rules
validation_rules = {
    "files": {
        "pattern_compliance": 1.0,    # 100% compliance
        "length_limits": True,
        "character_set": "[a-z0-9_-]"
    },
    "components": {
        "case_compliance": 1.0,       # 100% compliance
        "prefix_suffix": True,
        "descriptive_names": True
    },
    "documentation": {
        "section_format": True,
        "link_format": True,
        "metadata_format": True
    }
}
```

### 2. Quality Checks
See [[quality_metrics]] for implementation.

```python
# @quality_metrics
naming_quality = {
    "consistency": {
        "pattern_adherence": 0.95,    # 95% pattern compliance
        "case_consistency": 1.0,      # 100% case consistency
        "separator_usage": 1.0        # 100% separator consistency
    },
    "clarity": {
        "descriptive_names": 0.9,     # 90% descriptive quality
        "length_compliance": 0.95,    # 95% length compliance
        "abbreviation_usage": 0.8     # 80% abbreviation compliance
    }
}
```

## Implementation Details

### 1. Name Processing
```python
# @name_processor
class NameProcessor:
    """
    Process and validate names according to conventions.
    See [[validation_framework]] for validation rules.
    """
    def __init__(self):
        self.validator = NameValidator()
        self.formatter = NameFormatter()
        self.analyzer = NameAnalyzer()
    
    def process_name(self, name: str, context: Context) -> ProcessedName:
        """
        Process and validate a name.
        See [[naming_conventions]] for rules.
        """
        # Analyze context
        pattern = self._get_pattern(context)
        rules = self._get_rules(context)
        
        # Format name
        formatted_name = self.formatter.format(name, pattern)
        
        # Validate
        validation_result = self.validator.validate(
            formatted_name,
            rules
        )
        
        # Analyze
        analysis = self.analyzer.analyze(formatted_name)
        
        return ProcessedName(
            original=name,
            formatted=formatted_name,
            validation=validation_result,
            analysis=analysis
        )
    
    def _get_pattern(self, context: Context) -> Pattern:
        """Get naming pattern for context."""
        if context.type == "file":
            return self._get_file_pattern(context)
        elif context.type == "class":
            return self._get_class_pattern(context)
        elif context.type == "method":
            return self._get_method_pattern(context)
        else:
            raise ValueError(f"Unknown context type: {context.type}")
    
    def _get_rules(self, context: Context) -> List[Rule]:
        """Get validation rules for context."""
        return [
            Rule(rule_type, params)
            for rule_type, params in context.rules.items()
        ]
```

### 2. Name Validation
```python
# @name_validator
class NameValidator:
    """
    Validate names against conventions.
    See [[validation_framework]] for rules.
    """
    def __init__(self):
        self.rules = self._load_rules()
        self.patterns = self._load_patterns()
        self.checkers = self._init_checkers()
    
    def validate(self, name: str, context: Context) -> ValidationResult:
        """
        Validate a name against conventions.
        See [[quality_metrics]] for criteria.
        """
        # Get applicable rules
        rules = self._get_applicable_rules(context)
        
        # Run validations
        results = []
        for rule in rules:
            result = self._check_rule(name, rule)
            results.append(result)
        
        # Aggregate results
        return self._aggregate_results(results)
    
    def _check_rule(self, name: str, rule: Rule) -> RuleResult:
        """Check a single naming rule."""
        checker = self.checkers.get(rule.type)
        if not checker:
            raise ValueError(f"No checker for rule type: {rule.type}")
        
        return checker.check(name, rule.params)
    
    def _aggregate_results(self, results: List[RuleResult]) -> ValidationResult:
        """Aggregate rule check results."""
        return ValidationResult(
            valid=all(r.valid for r in results),
            issues=[issue for r in results for issue in r.issues],
            score=sum(r.score for r in results) / len(results)
        )
```

### 3. Name Analysis
```python
# @name_analyzer
class NameAnalyzer:
    """
    Analyze names for quality and patterns.
    See [[quality_metrics]] for criteria.
    """
    def __init__(self):
        self.metrics = QualityMetrics()
        self.patterns = PatternMatcher()
        self.analyzer = TextAnalyzer()
    
    def analyze(self, name: str) -> AnalysisResult:
        """
        Analyze name quality and characteristics.
        See [[analysis_tools]] for methods.
        """
        # Quality metrics
        quality = self._analyze_quality(name)
        
        # Pattern matching
        patterns = self._match_patterns(name)
        
        # Text analysis
        text_analysis = self._analyze_text(name)
        
        return AnalysisResult(
            quality=quality,
            patterns=patterns,
            text_analysis=text_analysis
        )
    
    def _analyze_quality(self, name: str) -> QualityMetrics:
        """Analyze name quality."""
        return self.metrics.compute_metrics(name, {
            "length": self._check_length(name),
            "clarity": self._check_clarity(name),
            "consistency": self._check_consistency(name)
        })
    
    def _match_patterns(self, name: str) -> List[Pattern]:
        """Match name against known patterns."""
        return self.patterns.find_matches(name)
```

## Implementation Examples

### 1. Name Pattern Matching
```python
# @pattern_matcher
class NamePatternMatcher:
    """
    Pattern matching implementation for names.
    See [[validation_framework]] for pattern rules.
    """
    def match_pattern(self, name: str, context: Context) -> MatchResult:
        """
        Match name against patterns.
        
        Example:
            >>> matcher = NamePatternMatcher()
            >>> result = matcher.match_pattern("BeliefUpdater", context)
            >>> print(f"Pattern match: {result.pattern}")
            Pattern match: {Role}{Type}
        """
        # Get applicable patterns
        patterns = self._get_patterns(context)
        
        # Try each pattern
        matches = []
        for pattern in patterns:
            if match := self._try_pattern(name, pattern):
                matches.append(match)
                print(f"Matched pattern: {pattern.name}")
        
        # Find best match
        best_match = self._select_best_match(matches)
        if best_match:
            print(f"Selected pattern: {best_match.pattern}")
        
        return MatchResult(
            matches=matches,
            best_match=best_match,
            confidence=self._calculate_confidence(matches)
        )
    
    def _try_pattern(self, name: str, pattern: Pattern) -> Optional[Match]:
        """
        Try matching a specific pattern.
        
        Example patterns:
        - PascalCase: BeliefUpdater
        - snake_case: belief_updater
        - kebab-case: belief-updater
        """
        # Convert pattern to regex
        regex = self._pattern_to_regex(pattern)
        
        # Try matching
        if match := re.match(regex, name):
            return Match(
                pattern=pattern,
                groups=match.groupdict(),
                score=self._calculate_match_score(match)
            )
        return None
    
    def _calculate_match_score(self, match: re.Match) -> float:
        """
        Calculate pattern match score.
        
        Example scoring:
        - Full match: 1.0
        - Partial match: 0.5-0.9
        - Weak match: < 0.5
        """
        # Base score
        score = 1.0
        
        # Adjust for group completeness
        groups = match.groupdict()
        if missing := [k for k, v in groups.items() if not v]:
            score -= len(missing) * 0.1
        
        # Adjust for pattern complexity
        score *= len(groups) / 10 + 0.5
        
        return min(max(score, 0.0), 1.0)
```

### 2. Name Formatting
```python
# @name_formatter
class NameFormatter:
    """
    Name formatting implementation.
    See [[ai_documentation_style]] for formatting rules.
    """
    def format_name(self, name: str, style: Style) -> FormattedName:
        """
        Format name according to style.
        
        Example:
            >>> formatter = NameFormatter()
            >>> result = formatter.format_name("beliefUpdater", Style.SNAKE_CASE)
            >>> print(f"Formatted: {result.formatted}")
            Formatted: belief_updater
        """
        # Normalize name
        normalized = self._normalize_name(name)
        print(f"Normalized: {normalized}")
        
        # Apply style
        formatted = self._apply_style(normalized, style)
        print(f"Formatted: {formatted}")
        
        # Validate result
        validation = self._validate_formatting(formatted, style)
        if not validation.is_valid:
            print(f"Validation issues: {validation.issues}")
        
        return FormattedName(
            original=name,
            normalized=normalized,
            formatted=formatted,
            validation=validation
        )
    
    def _normalize_name(self, name: str) -> str:
        """
        Normalize name for formatting.
        
        Example transformations:
        - beliefUpdater -> ['belief', 'updater']
        - belief_updater -> ['belief', 'updater']
        - belief-updater -> ['belief', 'updater']
        """
        # Split on case boundaries
        parts = re.findall('[A-Z][a-z]*|[a-z]+', name)
        
        # Handle special characters
        parts = [p.strip('_-') for p in parts]
        
        # Filter empty parts
        parts = [p for p in parts if p]
        
        return parts
    
    def _apply_style(self, parts: List[str], style: Style) -> str:
        """
        Apply naming style to parts.
        
        Example styles:
        - PascalCase: BeliefUpdater
        - camelCase: beliefUpdater
        - snake_case: belief_updater
        - kebab-case: belief-updater
        """
        if style == Style.PASCAL_CASE:
            return ''.join(p.capitalize() for p in parts)
        elif style == Style.CAMEL_CASE:
            return parts[0].lower() + ''.join(p.capitalize() for p in parts[1:])
        elif style == Style.SNAKE_CASE:
            return '_'.join(p.lower() for p in parts)
        elif style == Style.KEBAB_CASE:
            return '-'.join(p.lower() for p in parts)
        else:
            raise ValueError(f"Unknown style: {style}")
```

### 3. Name Suggestion
```python
# @name_suggester
class NameSuggester:
    """
    Name suggestion implementation.
    See [[naming_conventions]] for suggestion rules.
    """
    def suggest_names(self, name: str, context: Context) -> Suggestions:
        """
        Generate name suggestions.
        
        Example:
            >>> suggester = NameSuggester()
            >>> suggestions = suggester.suggest_names("blf_upd", context)
            >>> print(f"Suggestions: {suggestions.alternatives}")
            Suggestions: ['BeliefUpdater', 'belief_updater']
        """
        # Analyze name
        analysis = self._analyze_name(name)
        print(f"Name analysis: {analysis.summary}")
        
        # Generate alternatives
        alternatives = self._generate_alternatives(analysis, context)
        print(f"Generated {len(alternatives)} alternatives")
        
        # Rank suggestions
        ranked = self._rank_suggestions(alternatives, context)
        print(f"Top suggestion: {ranked[0]}")
        
        return Suggestions(
            original=name,
            alternatives=ranked,
            analysis=analysis
        )
    
    def _analyze_name(self, name: str) -> NameAnalysis:
        """
        Analyze name for suggestion generation.
        
        Example analysis:
        - Abbreviations: blf -> belief
        - Word boundaries: blf_upd -> belief_update
        - Common patterns: mgr -> manager
        """
        # Detect abbreviations
        abbrevs = self._detect_abbreviations(name)
        
        # Find word boundaries
        boundaries = self._find_word_boundaries(name)
        
        # Match common patterns
        patterns = self._match_common_patterns(name)
        
        return NameAnalysis(
            abbreviations=abbrevs,
            boundaries=boundaries,
            patterns=patterns
        )
    
    def _generate_alternatives(self, analysis: NameAnalysis, context: Context) -> List[str]:
        """
        Generate alternative names.
        
        Example generations:
        - Expand abbreviations
        - Apply naming patterns
        - Consider context
        """
        alternatives = []
        
        # Expand abbreviations
        if analysis.abbreviations:
            alternatives.extend(self._expand_abbreviations(analysis))
        
        # Apply patterns
        alternatives.extend(self._apply_patterns(analysis, context))
        
        # Consider context
        alternatives.extend(self._context_based_suggestions(analysis, context))
        
        return alternatives
    
    def _rank_suggestions(self, suggestions: List[str], context: Context) -> List[str]:
        """
        Rank name suggestions.
        
        Example ranking criteria:
        - Pattern match score
        - Context relevance
        - Clarity score
        """
        scored_suggestions = [
            (suggestion, self._score_suggestion(suggestion, context))
            for suggestion in suggestions
        ]
        
        # Sort by score
        scored_suggestions.sort(key=lambda x: x[1], reverse=True)
        
        return [s[0] for s in scored_suggestions]
```

## Integration Components

### 1. IDE Integration
```python
# @ide_integration
class IDEIntegration:
    """
    IDE integration for naming conventions.
    See [[cursor_integration]] for details.
    """
    def __init__(self):
        self.processor = NameProcessor()
        self.suggester = NameSuggester()
        self.formatter = NameFormatter()
    
    def process_identifier(self, name: str, context: Context) -> Suggestions:
        """
        Process identifier in IDE.
        See [[ide_plugins]] for implementation.
        """
        # Validate name
        result = self.processor.process_name(name, context)
        
        # Generate suggestions
        if not result.validation.valid:
            suggestions = self.suggester.suggest(name, context)
            return Suggestions(
                original=name,
                suggestions=suggestions,
                reason=result.validation.issues
            )
        
        return Suggestions(original=name, suggestions=[])
```

### 2. Git Integration
```python
# @git_integration
class GitIntegration:
    """
    Git hooks for naming convention enforcement.
    See [[git_workflow]] for details.
    """
    def __init__(self):
        self.validator = NameValidator()
        self.reporter = ValidationReporter()
    
    def pre_commit_hook(self, changes: List[Change]) -> HookResult:
        """
        Validate names in changed files.
        See [[git_hooks]] for implementation.
        """
        # Collect names
        names = self._collect_names(changes)
        
        # Validate names
        results = [
            self.validator.validate(name, self._get_context(name))
            for name in names
        ]
        
        # Generate report
        report = self.reporter.generate_report(results)
        
        return HookResult(
            valid=all(r.valid for r in results),
            report=report
        )
```

### 3. Documentation Integration
```python
# @doc_integration
class DocumentationIntegration:
    """
    Documentation system integration.
    See [[documentation_standards]] for guidelines.
    """
    def __init__(self):
        self.processor = NameProcessor()
        self.linker = DocumentationLinker()
        self.validator = DocumentationValidator()
    
    def process_documentation(self, doc: Document) -> ProcessedDocument:
        """
        Process names in documentation.
        See [[documentation_guide]] for rules.
        """
        # Extract names
        names = self._extract_names(doc)
        
        # Process names
        processed_names = [
            self.processor.process_name(name, self._get_context(name))
            for name in names
        ]
        
        # Update documentation
        updated_doc = self._update_documentation(doc, processed_names)
        
        # Validate links
        self.validator.validate_links(updated_doc)
        
        return updated_doc
```

## Best Practices

### 1. General Guidelines
- Use descriptive names
- Maintain consistent patterns
- Follow case conventions
- Limit name length

### 2. Documentation
- Follow [[documentation_standards]]
- Use [[ai_documentation_style]]
- Implement [[linking_patterns]]
- Validate with [[quality_metrics]]

### 3. Code Style
- Follow [[code_organization]]
- Use [[implementation_patterns]]
- Maintain [[code_quality]]
- Check [[style_guide]]

## Related Documentation
- [[documentation_standards]]
- [[knowledge_organization]]
- [[code_organization]]
- [[style_guide]]

## References
- [[implementation_patterns]]
- [[quality_metrics]]
- [[validation_framework]]
- [[code_quality]]