Shell function annotation standard

shell-function-annotation-standard.md

Shell Function Annotation Standard

Purpose

Maintain clarity in shell configuration files by documenting function origin, purpose, and status.

Standard Template

# =============================================================================
# Function: <function_name>
# Added: <YYYY-MM-DD>
# Source: <Claude|ChatGPT|Manual|StackOverflow|etc>
# Purpose: <brief one-line description>
# Usage: <example command with arguments>
# Status: <active|testing|deprecated|broken>
# Notes: <optional additional context>
# =============================================================================

Field Definitions

• Function: Primary function name (or alias if applicable)
• Added: Date added to config (ISO format: YYYY-MM-DD)
• Source: Where the function came from (AI assistant, manual creation, copied from docs, etc)
• Purpose: Brief description of what it does
• Usage: Example command showing typical invocation
• Status: Current state
  • active - working and regularly used
  • testing - experimental, may have issues
  • deprecated - superseded by better solution
  • broken - known to not work, kept for reference
• Notes: (Optional) Caveats, known issues, dependencies

Examples

Example 1: Working Function

# =============================================================================
# Function: gist-clip
# Added: 2025-11-12
# Source: Claude
# Purpose: Create GitHub gist from Windows clipboard via WSL
# Usage: gist-clip "description" "filename.md"
# Status: active
# Notes: Emoji encoding unreliable, prefer ASCII alternatives
# =============================================================================
pwsh-clip() {
    powershell.exe -NoProfile -Command '$OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Get-Clipboard'
}

gist-clip() {
    local desc="${1:-clipboard content}"
    pwsh-clip | gh gist create --desc "$desc" --public --filename "${2:-content.md}" -
}

Example 2: Deprecated Function

# =============================================================================
# Function: old-backup
# Added: 2024-03-15
# Source: Manual
# Purpose: Quick rsync backup to external drive
# Usage: old-backup /source /dest
# Status: deprecated
# Notes: Replaced by backup-safe.sh (includes verification and logging)
# =============================================================================

Example 3: Broken/Reference

# =============================================================================
# Function: docker-clean-all
# Added: 2024-08-22
# Source: StackOverflow
# Purpose: Nuclear option for Docker cleanup
# Usage: docker-clean-all
# Status: broken
# Notes: Destructive. Removed after C volume incident 2024-09-XX
# =============================================================================

Benefits

1. Future auditing: Quickly find and remove unused/broken functions
2. Context preservation: Remember why something was added
3. Source tracking: Know which AI assistant or resource provided the code
4. Status visibility: Identify experimental vs production-ready functions
5. Safe deprecation: Keep references without active use

Maintenance Commands

# Find all functions by source
grep -n "Source: Claude" ~/.bashrc

# Find deprecated functions
grep -n "Status: deprecated" ~/.bashrc

# Find functions added in specific month
grep -n "Added: 2025-11" ~/.bashrc

# List all annotated functions
grep -n "# Function:" ~/.bashrc

Recommendation

When AI assistants (Claude, ChatGPT, etc) provide shell functions or aliases, request they include this annotation format by default. Share this standard across sessions for consistency.

---

Template Version: 1.0
Created: 2025-11-12
Compatible with: bash, zsh, fish (with comment syntax adjustment)