Regarding comments ... the ## end sub ... was added by perltidy ... I wouldn't spend much time mucking with those types of comments :)
Now for real comments, this added comment isn't needed :) the information it adds is already provided by the code, and the information actually contradicts the code
path( $in )->move( $bak ); #Creates a copy of the original file
No, move is not copy, copy means duplicate, move means move , from here to there, from this name to that name, path $in move to path $bak
You could add # rename $in to $bak if move isn't part of your vocabulary ... even # backup $in to $bak ... but sub is invoked as Replace( $file, "$file-$bak" ); so its not exactly new information :)
Now you could say the sub Replace creates a copy of the original file before it edits it to ... that is a comment for the subroutine , what the subroutine is supposed to accomplish (strategy) ... subroutine comments before subroutine (at top of subroutine), not on lines of code (this is misleading)
This part ## will match more than what you want fix it I was probably wrong on that ... :) this is why testing exists :)
#say for @paths; if you're debugging dd()umper takes care of non-printableish chars ... so you know exactly what types of bytes you have ... some chars don't show up in the shell ... so use dd() ... perlrebackslash explains escape sequences as does chromatics free book Modern Perl
my $date = POSIX::strftime( '%Y-%m-%d', localtime ); #sets current date and time to be added to backup file Have you tried it? use POSIX;
my $date = POSIX::strftime( '%Y-%m-%d', localtime );
print "$date\n";
__END__
2014-09-04
Is 2014-09-04 a "date and time"? The variable is named $date so adding date in comment is repetition :) and there is no time in the string, even if localtime function is used
Also to be added to backup file seems like extra stuff since on the very next line you have my $bak = "$date.bak"; #date added to the .bak file
Adding comments like this to you code, and saving and keeping the file is a good idea, it helps you learn/remember things you were having trouble remembering... save it maybe as myproggie-2014-09-04-02-55-54-annotated.pl ... so a week a month a year from now you can read it and remember
But you should strive for correctness in commentary, because computers are dumb, they don't skip steps, so "date added to .bak file" isn't exactly true, its a string, its a suffix, for a backup filename, so date isn't added to file ... if the $variable names aren't informative enough, don't add comments, change the name
my $dateNow = POSIX::strftime( '%Y-%m-%d', localtime );
my $backupSuffix = $dateNow . ".bak";
...
my $backupFile = "$file-$backupSuffix";
Replace( $file, $backupFile );
Maybe $ymdToday ...
... $backupFile = "$file-$ymdToday.bak";
Or even $yyyymmdd ... "$file-$ymdToday.bak";
Remember your program outline in Re^16: search and replace strings in different files in a directory? That is a good for a first draft sketch:), but once you start giving good names to subs, you gotta keep going and give good variable names too ... names that are meaningful to you and your program ... good names beat good comments :) Strategy in Comments, Tactics in Code
Did I mention , every time you make big changes to your program , you should back it up, say myproggie-2014-09-04-02-16-54.pl, myproggie-2014-09-04-03-16-54.pl, ... ? each time you start work on a new subroutine start a new file...
Replace( $file, "$file-$bak" ); #sub Replace using it's 2 parameters as defined below
Instead of documenting Replace() where you use it, try documenting it where its defined, like
## Replace( $inputFilename, $backupFilename );
sub Replace {
my( $inputFilename, $backupFilename ) = @_;
...
## FixXmlEntities ( $inputFilename, $backupFilename );
sub FixXmlEntities {
my( $inputFilename, $backupFilename ) = @_;
...
## FixXmlEntities ( $inputFilename, $backupFilename );
sub FixXmlEntities {
my( $input, $backup ) = @_;
...
## FixUnencodedXmlEntities ( $inputFilename, $backupFilename );
## FixStrayXmlEntities ( $inputFilename, $backupFilename );
sub FixStrayXmlEntities {
my( $infile, $bakfile ) = @_;
...
}
What do you like? Whats memorable and correct?
So correct comments are good, good for learning, improving the quality of your varnames/subnames so you need less comments comes with practice time ... backup your files ... as you incrementally create twenty small programs until you're comfortable with the syntax/grammar/vocabulary of the language perl...
programming is a lot like carpentry except its ok to throw away your work and start over bytes are cheap:) |