docstring_standards

Docstring Standards

Core Principle

Write docstrings that are succinct and direct - avoid verbose explanations.

Docstring Requirements

• Succinct communication - Essential information only, no verbose explanations
• Direct language - Get to the point quickly
• Follow @documentation forbidden content rules:
  • No task references or historical processes
  • No abstract corporate speak
  • No development journey narratives
• External reader accessible - Assume zero project knowledge but keep it brief
• Practical focus - What they need to know, not extensive examples

Structure Guidelines

• Brief description - One clear sentence about what the function does
• Essential args/returns - Key parameters and return values only
• Minimal examples - Only when necessary for clarity
• No extensive prerequisites - Basic requirements only

Examples

✅ Good Docstring

def generate_daily_summary(date: str) -> Optional[DailySummary]:
    """Generate a daily summary from journal entries.
    
    Args:
        date: Date string in YYYY-MM-DD format.
        
    Returns:
        DailySummary object or None if no entries found.
    """

❌ Avoid Verbose Docstrings

def generate_daily_summary(date: str) -> Optional[DailySummary]:
    """Generate a daily summary from journal entries.
    
    This function orchestrates the complete workflow for generating daily summaries
    from journal entries. It handles the entire process from loading configuration
    to processing entries through AI and saving the final formatted results.
    
    ## Prerequisites
    - Journal files must exist in the expected directory structure
    - Configuration file must be properly set up with journal paths
    - AI provider must be configured with valid API keys
    
    ## Usage Examples
    ```python
    # Generate for today
    summary = generate_daily_summary("2025-01-15")
    
    # Handle the result
    if summary:
        print(f"Generated: {summary['summary']}")
    else:
        print("No entries found")
    ```
    
    ## Technical Context
    This function was created to replace the MCP-based approach...
    """