Crontab files use the hash symbol (#) for single-line comments, but many developers wonder about multi-line comment support. Unlike programming languages like C++ or Java, crontab has specific syntax rules for comments.

# This is a valid single-line comment in crontab
* * * * * command_to_execute

When documenting complex cron jobs, developers often need to:

• Explain the purpose of job groups
• Document dependencies between jobs
• Leave maintenance notes
• Mark temporary changes

The standard Vixie cron implementation (used in most Linux systems) only supports single-line comments. Each comment line must begin with #:

# Database backup jobs
# -------------------
# These jobs run nightly at 2am
0 2 * * * /usr/bin/backup-db

# Temporary debug job
# (Remove after bug #123 is fixed)
*/5 * * * * /usr/bin/debug-script

While /* */ syntax doesn't work, here are practical solutions:

1. Sequential Single-Line Comments

The most common approach:

####################################
# Database Maintenance Section     #
# Last updated: 2023-11-15         #
# Contact: team@example.com        #
####################################

# Primary backup (full)
0 2 * * * /usr/bin/full-backup

# Incremental backup
30 2 * * * /usr/bin/incr-backup

2. Using Here-Documents (Advanced)

For complex documentation, you can include a heredoc in your command:

# Documentation: <

Keep comments concise but informative
Use consistent formatting (e.g., header blocks)
Include modification dates
Mark temporary jobs clearly
Document the job's expected output location

################################################################
# SYSTEM MAINTENANCE JOBS                                      #
# Server: prod-web-01                                          #
# Last reviewed: 2023-11-01 by devops-team                     #
################################################################

# Log rotation - runs daily at midnight
0 0 * * * /usr/sbin/logrotate /etc/logrotate.conf

# Security updates - weekly on Sunday at 3am
0 3 * * 0 /usr/bin/apt-get update && /usr/bin/apt-get upgrade -y

################################################################
# APPLICATION-SPECIFIC JOBS                                   #
################################################################

# Cache warming - every 15 minutes during business hours
*/15 8-18 * * 1-5 /usr/bin/php /var/www/warm-cache.php

When storing crontabs in version control:

Use meaningful commit messages that reference job changes
Consider splitting large crontabs into multiple files
Document why jobs exist, not just what they do


Crontab files support single-line comments using the hash symbol (#), but lack native support for multi-line comment blocks like /* */ found in programming languages. This limitation can be frustrating when documenting complex cron jobs.
While you cannot use C-style /* */ comments directly in crontab, these methods achieve similar results:
# Option 1: Sequential single-line comments
# This is a multi-section comment in crontab
# Each line must begin with #
# Works well for readability

# Option 2: Here-document workaround (Bash syntax)
0 * * * * /bin/bash <<'EOF'
# This entire block is effectively a "multi-line comment"
# because it's a no-op command
:
EOF

Here's how to document a complex backup job:
# ===============================
# Database Backup Configuration
# Runs every Sunday at 2:30 AM
# Maintains 4 weeks of backups
# ===============================
30 2 * * 0 /usr/local/bin/backup-db.sh full
# Weekly incremental backup
30 2 * * 1-6 /usr/local/bin/backup-db.sh incremental


Use consistent comment headers for different job sections
Include timestamps in comments when modifying crontab
Document the purpose and expected output of each job
Consider maintaining external documentation for complex setups

Modern editors can help with crontab commenting:
# Vim folding example (add to .vimrc)
autocmd FileType crontab setlocal commentstring=#\ %s
autocmd FileType crontab setlocal foldmethod=marker
autocmd FileType crontab setlocal foldmarker=#region,#endregion