=head2 Analyzing Code
Perltidy reports any obvious issues that are found during formatting, such as
-unbalanced braces. But Several parameters are available for making certain
+unbalanced braces. But several parameters are available for making certain
additional checks for issues which might be of interest to a programmer.
=over 4
These are variables which are re-declared in the scope of a variable with the
identical name. This can be confusing (perhaps not when the code is first
-written, but possibly later during maintenance work). Note that this is
+written, but possibly later during maintenance work). This issue can be
+avoided by renaming one of the conflicting variables. Note that this is
similar to the B<Perl::Critic> policy B<Variables::ProhibitReusedNames>.
=item B<s: sigil change but reused bareword>
These are variables which have the same bareword name but a different sigil
(B<$>, B<@>, or B<%>) as another variable in the same scope. For example, this
occurs if variables B<$data> and B<%data> share the same scope. This can be
-confusing.
+confusing and can be avoided by renaming one of the variables.
=item B<p: package-crossing variables>
These are lexical variables which are declared in one package and still visible
-in subroutines of a different package in the same file. This can be confusing.
-This check is limited to packages which are not enclosed in block braces in
-order skip temporary package changes.
+in subroutines of a different package in the same file. This can be confusing,
+and it might cause the program to run differently, or fail, if the the packages
+were ever split into separate files. This issue can usually be avoided by
+placing code in block braces of some type. For example, this issue is often
+found in test code, and might be fixed by using the structure
+
+ main();
+
+ sub main { #<<<
+ ## old main code goes here
+ }
+
+The B<non-indenting-braces> comment C<#<<<> is not required but will keep the
+indentation of the old code unchanged. It should be noted that this check is
+limited to packages which are not enclosed in block braces in order skip
+temporary package changes.
=item B<u: unused variables>
These are variables which are declared with a C<my> and not referenced again
within their scope. Calling them B<unused> is convenient but not really
-accurate. There are many reasons for having such variables. For example, they
-might occur in a list of values provided by another routine or data structure,
-and therefor must be listed, even though they might not be referenced again. Or
-they might be defined for possible future program development, clarity or
-debugging. But sometimes they can occur due to being orphaned by a coding
-change, due to a misspelling, or by having an unintentional preceding C<my>.
-So it is worth reviewing them, especially for new code. Here is an
-example of an unused variable in a script located with this method:
+accurate; this is a "gray area" for a program. There are many reasons for
+having such variables. For example, they might occur in a list of values
+provided by another routine or data structure, and therefor must be listed,
+even though they might not be referenced again. Or they might be defined for
+possible future program development, clarity or debugging. B<But> sometimes
+they can occur due to being orphaned by a coding change, due to a misspelling,
+or by having an unintentional preceding C<my>. So it is worth reviewing them,
+especially for new code. Here is an example of an unused variable in a script
+located with this method:
BEGIN { my $string = "" }
...
$string .= "ok";
-This looks nice, but the scope of the C<my> declaration is limited to the
-surrounding braces, so it is not the same variable as the other C<$string>
-and is therefore reported as unused. This problem would have
+This looks nice at first glance, but the scope of the C<my> declaration is
+limited to the surrounding braces, so it is not the same variable as the other
+C<$string> and must therefore be reported as unused. This problem would have
also been caught by perl if the author had used C<strict>.
=back
my $debug_file = $self->{_debug_file};
my $is_encoded_data = $self->{_is_encoded_data};
-Vertical alignment is automatic, but stops at blank lines. So a blank line can
-be inserted to stop an unwanted alignment. So, for example, we can
-can insert a blank line to break the alignment in the above example
-like this:
+Vertical alignment is automatic unless it has been deactivated by one of its
+controls, but it always stops and tries to restart at blank lines. So a blank
+line can be inserted to stop an unwanted alignment. So, for example, we can
+can insert a blank line to break the alignment in the above example like this:
my $self = shift;
1, 4, 6, 4, 1,);
#>>>
+A related comment control is B<--code-skipping>, indicated with '#<<V>. and
+'#>>V>', which simply passes lines of code to the output without tokenization.
+This is useful for some extended syntaxes. Another is
+B<--non-indenting-braces>, indicated by placing a side comment '#<<<' following
+a block brace, which prevents code within the marked braces from getting an
+extra level indentation. This is useful if we want to put braces around code
+and want to minimize the changes in formatting.
+
=head2 Finding Unused Variables
Perltidy has several parameters which can assist in locating problems in code.
projects / perltidy.git / commitdiff