code-documentation-standards

name	code-documentation-standards
description	Comprehensive code documentation standards and guidelines for maintaining up-to-date documentation across Python, HTML, CSS, and JavaScript codebases. Use when creating or modifying code to ensure proper documentation practices and maintainable code.

Code Documentation Standards

⚠️ Repo Reality Check (read this first)

This skill's later examples are domain-generic and don't always match what the Chuuk Dictionary repo actually does. Concrete things to know:

• The backend is a single-file monolith (app.py). New documentation should be section comments inside app.py, not new module READMEs. See the flask-api-development skill for the route surface.
• The frontend uses CSS Modules per page (e.g. Compose.module.css) — document component contracts inline with TypeScript types, not external markdown.
• Database contracts live as JSON shapes in DictionaryDB, UserDB, and PublicationManager — when adding a field, update the docstring on the writing method, not just the schema.
• There is no markdownlint setup in the repo. Don't invoke markdownlint in any tooling.
• Per the project's standing instructions: do not create new markdown docs to describe code changes unless explicitly asked. Update existing docs/code comments instead.

Core Principle

ALWAYS maintain up-to-date documentation when creating or modifying code. Documentation must be updated simultaneously with code changes. ALWAYS fix markdown validation errors promptly before committing any changes.

Pre-Commit Markdown Validation

Before any commit, ALWAYS:

1. Run markdown validation on all .md files in the repository
2. Fix all markdown syntax errors including:
   • Unclosed code blocks
   • Missing link destinations
   • Invalid heading structures
   • Broken table formatting
   • Incorrect list indentation
3. Validate code block syntax in documentation
4. Check internal links are properly formatted
5. Ensure consistent formatting across all markdown files

Documentation Requirements

1. Python Functions/Classes

def process_document(file_path: str, patterns: List[str]) -> ProcessResult:
    """
    Process a document for redaction using specified patterns.
    
    Args:
        file_path (str): Path to the document file to process
        patterns (List[str]): List of redaction patterns to apply
        
    Returns:
        ProcessResult: Object containing processed document and metadata
        
    Raises:
        FileNotFoundError: If the specified file doesn't exist
        ValidationError: If patterns are invalid
        
    Example:
        >>> result = process_document('doc.pdf', ['ssn', 'email'])
        >>> print(result.redacted_count)
    """
    pass

2. Class Documentation

class DocumentProcessor:
    """
    Handles document processing operations for various file formats.
    
    This class provides methods for parsing, analyzing, and transforming
    documents while maintaining original formatting and metadata.
    
    Attributes:
        supported_formats (List[str]): File formats supported by processor
        max_file_size (int): Maximum file size in bytes
        
    Example:
        >>> processor = DocumentProcessor()
        >>> result = processor.process('document.pdf')
    """
    
    def __init__(self, config: ProcessingConfig = None):
        """Initialize processor with optional configuration."""
        pass

3. Template Documentation

<!-- 
Template: translation_interface.html
Purpose: Main interface for Chuukese-English translation
Variables:
  - dictionary_entries: List of recent dictionary entries
  - user_translations: User's translation history
  - cultural_context: Cultural context data for assistance
Dependencies:
  - static/css/translation.css
  - static/js/translation-ui.js
  - Bootstrap 5.1+
-->
<div class="translation-container">
    <!-- Translation form content -->
</div>

4. CSS Class Documentation

/* 
 * Chuukese Text Display
 * Purpose: Styles for displaying Chuukese text with proper accent handling
 * Usage: Apply to containers holding Chuukese language content
 * Dependencies: Requires font-family supporting Unicode accents
 */
.chuukese-text {
    font-family: 'Noto Sans', 'Arial Unicode MS', sans-serif;
    font-size: 1.1em;
    line-height: 1.5;
    direction: ltr;
}

/* 
 * Responsive adaptation: Increase font size on mobile
 * Context: Better readability for accented characters
 */
@media (max-width: 768px) {
    .chuukese-text {
        font-size: 1.2em;
    }
}

5. JavaScript Function Documentation

/**
 * Normalize Chuukese text for search operations
 * @param {string} text - The Chuukese text to normalize
 * @param {boolean} preserveAccents - Whether to preserve accent marks
 * @returns {string} Normalized text suitable for searching
 * @throws {TypeError} If text is not a string
 * 
 * @example
 * const normalized = normalizeChuukeseText('kápás', false);
 * console.log(normalized); // 'kapas'
 */
function normalizeChuukeseText(text, preserveAccents = true) {
    if (typeof text !== 'string') {
        throw new TypeError('Text parameter must be a string');
    }
    // Implementation...
}

Documentation Standards by Context

Database Models

class DictionaryEntry(Base):
    """
    Represents a Chuukese-English dictionary entry.
    
    This model stores bilingual dictionary data with cultural context,
    pronunciation guides, and usage information for language learning
    and translation applications.
    
    Attributes:
        chuukese_word (str): Primary Chuukese term (required)
        english_definition (str): English definition or translation
        pronunciation (str): IPA or phonetic pronunciation guide
        cultural_context (str): Cultural significance and usage notes
        part_of_speech (str): Grammatical category (noun, verb, etc.)
        difficulty_level (str): Learning difficulty (beginner/intermediate/advanced)
        usage_frequency (float): Frequency score 0.0-1.0
        
    Relationships:
        phrases: Related phrase entries using this word
        translations: Translation pairs containing this entry
        
    Example:
        >>> entry = DictionaryEntry(
        ...     chuukese_word="chomong",
        ...     english_definition="to help, assist",
        ...     cultural_context="Community cooperation value"
        ... )
    """
    __tablename__ = 'dictionary_entries'
    
    id = Column(Integer, primary_key=True)
    chuukese_word = Column(String(200), nullable=False, index=True)
    # ... rest of model

API Routes

@app.route('/api/translate', methods=['POST'])
def translate_text():
    """
    Translate text between Chuukese and English.
    
    Endpoint for bidirectional text translation with quality assessment
    and cultural context preservation.
    
    Request Body:
        {
            "text": "string - Text to translate (required)",
            "source_language": "string - Source language code (required)",
            "target_language": "string - Target language code (required)",
            "include_cultural_context": "boolean - Include cultural notes
                                        (optional, default: false)"
        }
    
    Response:
        {
            "translated_text": "string - Translated result",
            "quality_score": "float - Translation quality 0.0-1.0",
            "cultural_notes": "array - Cultural context information (if requested)",
            "confidence": "float - Translation confidence score"
        }
    
    Status Codes:
        200: Translation successful
        400: Invalid request parameters
        422: Translation quality too low
        500: Internal server error
    
    Example:
        >>> POST /api/translate
        >>> {
        ...     "text": "chomong",
        ...     "source_language": "chuukese",
        ...     "target_language": "english"
        ... }
        
        Response:
        {
            "translated_text": "to help",
            "quality_score": 0.95,
            "confidence": 0.98
        }
    """
    pass

Best Practices

1. Consistency Standards

• Use consistent parameter naming across similar functions
• Maintain uniform documentation formatting
• Follow established patterns for each language/framework
• Update documentation immediately when code changes
• Fix all markdown validation errors before committing

2. Content Guidelines

• Write for developers who don't know the codebase
• Include practical examples whenever possible
• Document edge cases and error conditions
• Explain the "why" behind implementation decisions

3. Cultural Context Documentation (Chuukese Project Specific)

• Document cultural significance of Chuukese terms
• Explain traditional concepts that may not translate directly
• Note appropriate usage contexts (formal/informal, traditional/modern)
• Include pronunciation guides for language learners

4. Maintenance Requirements

• Review documentation during code reviews
• Update documentation in the same commit as code changes
• Mark deprecated functions with alternatives
• Remove documentation for deleted code
• Validate markdown syntax before each commit

5. Quality Checks

• Verify all parameters are documented
• Ensure examples are current and functional
• Check that return types match actual implementation
• Validate that error conditions are accurately described
• Run markdown linting tools on all documentation

6. Markdown Validation Process

MANDATORY before every commit:

1. Syntax Validation:

   # Check for markdown syntax errors
   markdownlint **/*.md
   

2. Code Block Validation:

   • Ensure all code blocks have proper opening/closing backticks
   • Verify language tags are correct (python, javascript, html, css)
   • Test that code examples are syntactically valid

3. Link Validation:

   • Check all internal links reference existing files/sections
   • Verify external links are accessible
   • Ensure proper markdown link syntax: [text](url)

4. Structure Validation:

   • Confirm heading hierarchy is logical (h1 → h2 → h3)
   • Verify lists have consistent indentation
   • Check table formatting is complete

5. Common Fixes:

   • Close unclosed code blocks with proper backticks
   • Fix malformed tables with proper pipe alignment
   • Correct broken link references
   • Standardize heading styles (#, ##, ###)
   • Fix list item indentation and nesting

Templates

Function Documentation Template

def function_name(param1: Type1, param2: Type2 = default) -> ReturnType:
    """
    Brief description of what the function does.
    
    Longer description if needed, explaining the purpose and any
    important implementation details or assumptions.
    
    Args:
        param1 (Type1): Description of first parameter
        param2 (Type2, optional): Description with default value
        
    Returns:
        ReturnType: Description of return value
        
    Raises:
        ExceptionType: When this exception occurs
        
    Example:
        >>> result = function_name(value1, value2)
        >>> print(result)
        
    Note:
        Any special considerations or warnings
    """

Class Documentation Template

class ClassName:
    """
    Brief description of the class purpose.
    
    Detailed explanation of what the class represents,
    its main responsibilities, and how it fits into
    the larger system.
    
    Attributes:
        attr_name (Type): Description of attribute
        
    Example:
        >>> instance = ClassName(param)
        >>> result = instance.method()
        
    See Also:
        RelatedClass: For related functionality
    """

Dependencies

• Follow project-specific documentation tools
• Use type hints for Python functions
• Include JSDoc for JavaScript when applicable
• Maintain README files for project overviews

Validation Criteria

Proper documentation should:

• ✅ Explain the purpose clearly and concisely
• ✅ Document all parameters and return values
• ✅ Include practical usage examples
• ✅ Note error conditions and exceptions
• ✅ Use consistent formatting and style
• ✅ Stay current with code changes
• ✅ Provide cultural context for Chuukese-specific terms
• ✅ Pass markdown validation without errors
• ✅ Have properly formatted code blocks and links
• ✅ Use consistent heading structure and list formatting

Pre-Commit Workflow

MANDATORY checklist before every commit:

1. ✅ Code documentation updated
2. ✅ Markdown files validated and errors fixed
3. ✅ Code blocks properly formatted with language tags
4. ✅ All links functional and properly formatted
5. ✅ Heading hierarchy follows logical structure
6. ✅ Examples tested and verified working

Tools for validation:

• markdownlint for syntax checking
• VS Code markdown preview for visual verification
• Link checkers for external references
• Code syntax validators for embedded examples