# 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]]