Considering Code Documentation

I was procrastinating about a work project, thinking about magnets, thinking about crushers, thinking about thermite, when I thought about my status tracker.

It goes by the name status.pl because status is already a DBus utility. I made some other decisions relating to command-line interface, moving away from a cool idea I had a few years ago that hasn't aged well. I changed it to record.pl, which isn't similarly overloaded on my system, at least, and wrote a few flags for it, mostly for overkill. I mean, at core, it's because Len Budney convinced me my scripts needed manners, especially it not doing anything when just called.

So, I wrote this. All the details are tucked in Status.pm, which I am not sharing and which needs an overhaul too. All in all, I am reasonably happy with this; If there was a useless use of sub signatures award, I think this'd be a contender, but both that and postderef are used in get_records.pl,  so it's okay. (I put no warnings because I'm running 5.26 on my desktop, but it is likely that I'll copy this to cluster machines running our 5.20 or the system 5.10 Perls, which would need the warnings.) I could and probably should go without IO::Interactive, but still.

So, my question is, beyond the user documentation that gets passed through Pod::Usage, what documentation does this program need? I'm always at a loss for examples of what is needed. In general, programmers discount documentation; most editor themes I see make comments gray and muted, which has always angered me, but looking at this (and yes, it's a slight case) I'm at a loss to decide what would be important to add.

So, what comments would you add? What do you find wanting?

(If desired, to add to this conversation, I can add the display section and the module.)

	#!/usr/bin/env perl
	use strict ;
	use warnings ;
	use feature qw{ postderef say signatures state } ;
	no warnings qw{ experimental::postderef experimental::signatures } ;
	use Carp ;
	use Getopt::Long ;
	use IO::Interactive qw{ interactive } ;
	use Pod::Usage ;
	use lib $ENV{ HOME } . '/lib' ;
	use Status ;
	my $config = config() ;
	if ( $config->{ status } =~ /\w/ ) {
	if ( set_status( $config->{ status } ) ) {
	say { interactive } qq{\t$config->{status}};
	}
	else {
	croak q{Could not write record: $!};
	}
	}
	exit ;
	sub config () {
	my $config ;
	GetOptions(
	'man' => \$config->{ man },
	'help' => \$config->{ help },
	'status=s' => \$config->{ status },
	) ;
	pod2usage( { -verbose => 2, -exitval => 1 } ) if $config->{ man } ;
	pod2usage( 1 ) && exit if $config->{ help } || !$config->{ status } ;
	return $config ;
	}
	=head1 NAME
	record.pl - what I did today
	=head1 SYNOPSIS
	record.pl -s status
	record.pl -h
	record.pl -m
	=head1 DESCRIPTION
	Stores records of daily activity in MongoDB to be pulled out later
	as a daily report to Phillip.
	=head1 OPTIONS
	=over 4
	=item B<-s>, B<--status>
	The text of the report. Required.
	=item B<-h>, B<--help>
	Display this text
	=item B<-m>, B<--man>
	Display the man pages, written in POD form
	=back
	=head1 LICENSE
	This is released under the Artistic
	License. See L<perlartistic>.
	=head1 AUTHOR
	Dave Jacoby L<jacoby.david@gmail.com>
	=cut

view raw record.pl hosted with ❤ by GitHub