Each programmer will, of course, have his or her own preferences in
regards to formatting, but there are some general guidelines that will
-make your programs easier to read, understand, and maintain.
+make your programs easier to read, understand, and maintain.
The most important thing is to run your programs under the B<-w>
flag at all times. You may turn it off explicitly for particular
-portions of code via the C<$^W> variable if you must. You should
+portions of code via the C<use warnings> pragma or the C<$^W> variable
+if you must. You should
also always run under C<use strict> or know the reason why not.
The C<use sigtrap> and even C<use diagnostics> pragmas may also prove
useful.
Regarding aesthetics of code lay out, about the only thing Larry
-cares strongly about is that the closing curly brace of
+cares strongly about is that the closing curly bracket of
a multi-line BLOCK should line up with the keyword that started the construct.
Beyond that, he has other preferences that aren't so strong:
=item *
Don't be afraid to use loop labels--they're there to enhance
-readability as well as to allow multi-level loop breaks. See the
+readability as well as to allow multilevel loop breaks. See the
previous example.
=item *
Avoid using grep() (or map()) or `backticks` in a void context, that is,
-when you just throw away their return values. Those functions all
+when you just throw away their return values. Those functions all
have return values, so use them. Otherwise use a foreach() loop or
the system() function instead.
Choose mnemonic identifiers. If you can't remember what mnemonic means,
you've got a problem.
-=item *
+=item *
While short identifiers like $gotit are probably ok, use underscores to
separate words. It is generally easier to read $var_names_like_this than
C<strict>. Other modules should begin with a capital letter and use mixed
case, but probably without underscores due to limitations in primitive
file systems' representations of module names as files that must fit into a
-few sparse bites.
+few sparse bytes.
=item *
-You may find it helpful to use letter case to indicate the scope
-or nature of a variable. For example:
+You may find it helpful to use letter case to indicate the scope
+or nature of a variable. For example:
- $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
- $Some_Caps_Here package-wide global/static
- $no_caps_here function scope my() or local() variables
+ $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
+ $Some_Caps_Here package-wide global/static
+ $no_caps_here function scope my() or local() variables
-Function and method names seem to work best as all lowercase.
-E.g., $obj-E<gt>as_string().
+Function and method names seem to work best as all lowercase.
+E.g., $obj-E<gt>as_string().
You can use a leading underscore to indicate that a variable or
function should not be used outside the package that defined it.
=item *
Line up corresponding things vertically, especially if it'd be too long
-to fit on one line anyway.
+to fit on one line anyway.
- $IDX = $ST_MTIME;
- $IDX = $ST_ATIME if $opt_u;
- $IDX = $ST_CTIME if $opt_c;
- $IDX = $ST_SIZE if $opt_s;
+ $IDX = $ST_MTIME;
+ $IDX = $ST_ATIME if $opt_u;
+ $IDX = $ST_CTIME if $opt_c;
+ $IDX = $ST_SIZE if $opt_s;
mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
chdir($tmpdir) or die "can't chdir $tmpdir: $!";
Always check the return codes of system calls. Good error messages should
go to STDERR, include which program caused the problem, what the failed
-system call and arguments were, and VERY IMPORTANT) should contain the
+system call and arguments were, and (VERY IMPORTANT) should contain the
standard system error message for what went wrong. Here's a simple but
sufficient example:
=item *
-Line up your translations when it makes sense:
+Line up your transliterations when it makes sense:
tr [abc]
[xyz];
Think about reusability. Why waste brainpower on a one-shot when you
might want to do something like it again? Consider generalizing your
code. Consider writing a module or object class. Consider making your
-code run cleanly with C<use strict> and B<-w> in effect. Consider giving away
+code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in effect
+Consider giving away
your code. Consider changing your whole world view. Consider... oh,
never mind.