Colored Comments

A powerful Sublime Text plugin for creating more readable and organized comments throughout your code. Colored Comments allows you to highlight different types of comments with custom colors, search across your entire project for tagged comments, and maintain code documentation standards.

The plugin was heavily inspired by Better Comments by aaron-bond but has been completely rewritten with modern async architecture and enhanced functionality.

✨ Features

• 🎨 Colorful Comment Highlighting - Automatically highlight comments based on configurable tags
• 🔍 Project-wide Tag Search - Quickly find all TODO, FIXME, and custom tags across your entire project
• ⚡ Async Performance - Non-blocking file scanning with optimized batch processing
• 🎯 Smart Preview - Preview tag locations without losing your current position
• 📋 Enhanced Quick Panel - Rich HTML formatting with emojis and file context
• ⚙️ Fully Configurable - Customize everything from tags to file scanning behavior
• 🔄 Continuation Support - Continue highlighting across multiple comment lines
• 🚀 Modern Architecture - Built with async/await and optimized for large projects

🚀 Quick Start

1. Install the plugin via Package Control
2. Add comment tags to your code:

# TODO: Implement user authentication
   # FIXME: Fix memory leak in data processing
   # ! Important: This affects security
   # ? Question: Should we cache this result?

1. Use Ctrl+Shift+P → “Colored Comments: List All Tags” to search your project
2. Customize tags and colors in your settings

📖 Available Commands

⚙️ Configuration

Global Settings

Configure the plugin by editing Preferences → Package Settings → Colored Comments → Settings:

{
    // Enable debug logging
    "debug": false,

    // Enables continued matching of the previous tag
    "continued_matching": true,

    // Character to continue matching on
    "continued_matching_pattern": "-",

    // Automatically continue highlighting based on previous line
    "auto_continue_highlight": false,

    // Delay in milliseconds before applying decorations (debounce)
    "debounce_delay": 300,

    // Shows comment icon next to comments
    "comment_icon_enabled": false,

    // Which comment icon to use (comment, dots)
    "comment_icon": "dots",

    // Syntax files to ignore
    "disabled_syntax": [
        "Packages/Text/Plain text.tmLanguage",
        "Packages/Markdown/MultiMarkdown.sublime-syntax"
    ]
}

Continued Matching

When enabled, comments can span multiple lines with continuation:

# TODO: Implement user authentication system
# - Check password strength requirements
# - Add two-factor authentication support
# - Integrate with OAuth providers
# This comment won't be highlighted (no continuation marker)

File Scanning Settings

Control which files are scanned during project-wide tag searches:

{
    // File extensions to skip when scanning for tags
    "skip_extensions": [
        ".pyc", ".class", ".exe", ".dll", ".zip", ".jpg", ".mp4", ".pdf"
    ],

    // Directory names to skip when scanning
    "skip_dirs": [
        "__pycache__", ".git", "node_modules", ".vscode", "build", "dist"
    ]
}

🏷️ Tag Configuration

Default Tags

The plugin comes with these default tags:

Custom Tags

Add your own tags or override defaults:

{
    "tags": {
        "NOTE": {
            "scope": "comments.note",
            "identifier": "NOTE[:]?|note[:]?",
            "is_regex": true,
            "ignorecase": true,
            "icon_emoji": "📝"
        },
        "HACK": {
            "scope": "comments.hack",
            "identifier": "HACK[:]?|hack[:]?",
            "is_regex": true,
            "icon_emoji": "🔨",
            "outline": true
        }
    }
}

Tag Properties

Each tag supports these properties:

• identifier - Text or regex pattern to match (required)
• **is_regex** - Set to true if identifier is a regex pattern
• ignorecase - Case-insensitive matching
• scope - Color scheme scope name
• icon_emoji - Emoji shown in quick panel and previews
• underline - Enable solid underline
• stippled_underline - Enable stippled underline
  
• squiggly_underline - Enable squiggly underline
• outline - Enable outline only (no background fill)
• priority - Matching priority (lower numbers = higher priority)

Advanced Tag Examples

{
    "tags": {
        // Simple plaintext tag
        "BUG": {
            "identifier": "BUG:",
            "scope": "comments.bug",
            "icon_emoji": "🐛"
        },

        // Regex tag with high priority
        "CRITICAL": {
            "identifier": "CRITICAL[!]*:?",
            "is_regex": true,
            "priority": -1,
            "scope": "comments.critical",
            "icon_emoji": "🚨",
            "outline": true,
            "underline": true
        },

        // Case-sensitive tag
        "API": {
            "identifier": "API:",
            "ignorecase": false,
            "scope": "comments.api",
            "icon_emoji": "🔌"
        }
    }
}

🎨 Color Scheme Integration

Automatic Template Injection

When you use “Edit Color Scheme”, the plugin automatically injects comment color definitions:

{
    "rules": [
        {
            "name": "Comments: TODO",
            "scope": "comments.todo",
            "foreground": "var(bluish)"
        },
        {
            "name": "Comments: FIXME", 
            "scope": "comments.fixme",
            "foreground": "var(redish)"
        },
        {
            "name": "Comments: Important",
            "scope": "comments.important", 
            "foreground": "var(orangish)"
        }
        // ... more comment styles
    ]
}

Built-in Color Variables

Use these predefined color variables in your color scheme:

• var(redish) - Red tones
• var(orangish) - Orange tones
  
• var(yellowish) - Yellow tones
• var(greenish) - Green tones
• var(bluish) - Blue tones
• var(purplish) - Purple tones
• var(pinkish) - Pink tones
• var(cyanish) - Cyan tones

🔍 Tag Search Features

Project-wide Search

Search for tags across your entire project with advanced filtering:

1. All Tags: Ctrl+Shift+P → “Colored Comments: List All Tags”
2. Filtered Search: Choose specific tag types from the input handler
3. Current File Only: Search only the active file

Rich Quick Panel

The search results show: - Tag Type with emoji icon - File Location with relative path - Line Number and preview - Syntax Highlighting in preview - HTML Formatting for better readability

Preview Navigation

• Preview Mode - Hover over results to preview without navigation
• Transient Views - Quick preview without opening permanent tabs
• Position Restoration - Return to original position when canceling
• Smart Navigation - Jump to exact line and column

🚀 Performance Features

Async Architecture

• Non-blocking file scanning
• Batch processing for large projects
• Debounced updates to prevent excessive processing
• Smart caching of comment regions

Optimized File Scanning

• Heuristic detection of text files
• Configurable filtering to skip binary files
• Directory exclusion for faster scanning
• Progress reporting during large scans

Memory Efficiency

• Lazy loading of file contents
• Temporary views for unopened files
  
• Cleanup routines to prevent memory leaks
• Optimized data structures for large projects

🛠️ Development & Debugging

Debug Mode

Enable debug logging to troubleshoot issues:

{
    "debug": true
}

Then use “Colored Comments: Show Debug Logs” to view detailed information about: - Tag regex compilation - File scanning progress - Comment region detection - Performance metrics

Contributing

The plugin welcomes contributions! Key areas:

• Tag patterns for new languages
• Color scheme templates
• Performance optimizations
• UI/UX improvements

🙏 Credits

• Inspired by Better Comments by aaron-bond
• Built on sublime_aio for async support
• Uses sublime_lib for enhanced functionality

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.