comment on

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
[download]

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
[download]

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 );
[download]

Maybe

$ymdToday ...
... $backupFile = "$file-$ymdToday.bak";
[download]

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 ) = @_;
    ...
}
[download]

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:)

In reply to Re^21: search and replace strings in different files in a directory by Anonymous Monk
in thread search and replace strings in different files in a directory by PitifulProgrammer

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		`&`
	<		`<`
	>		`>`
	[		`[`
	]		`]`

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.