Comment your code with Smart::Comments

Normally we comment our code so that humans (including ourselves) can
understand it later on. However with ``Smart::Comments'' it becomes
possible to have comments which are not only useful in comprehending our
code, but also in *debugging* our code.

With ``Smart::Comments'' enabled, when a special comment sequence is
seen (``###'' by default) debugging output is produced:

use Smart::Comments;

### [] Running backups...

my $backup_dir = get_backup_host();

### Backing up files to: $backup_dir

foreach my $file (@manifest) { ### Copying files... % done
backup($file, $backup_dir);
}

### [] Backup complete...

With ``Smart::Comments'' enabled, output similar to the following would
be seen:

### [Fri Feb 25 12:14:34 2011] Running backups...

### Backing up files to: '/mnt/backup'

Copying files........ 64% done

### [Fri Feb 25 12:17:57 2011] Done...

One of great advantages of ``Smart::Comments'' is that the ``use
Smart::Comments'' line can simply be removed (or commented away) when
done, and all our smart comments are then simply ignored by Perl.
There's no requirement that ``Smart::Comments'' be installed on the
production systems, and no risk that that it may interfere with your
code.

You can read more about ``Smart::Comments'' on the
CPAN .