![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
Coding rules for Perl
Feb. 25th, 2010 05:03 pmWorking to debug a particularly nasty third-party piece of Perl, I realised that it broke almost all my cardinal coding rules. Offences included:
Sloppy indentation. Completely unacceptable. Most modern editors provide syntax aware indentation. If you're working with an editor that doesn't indent correctly, then upgrade to one that does.
Poor line wrapping. Lines should be wrapped at around 72 characters, not because people still use fixed size terminals but because very long lines are much harder to read and debug.
Limited use of subroutines. Code should always be chopped up into reasonable sized logical subroutines. This should be done even if the code is only used once, because it makes the code much easier to debug using the next command. It also makes it possible to scope variables.
Poor variable scoping. Variables should be declared with the most limited scope possible, even if this increases the number of arguments that need to be passed in subroutine calls. Global variables should be used extremely sparingly and magic variables such as
Hardwiring of patterns. In cases where patterns are unlikely to vary, e.g. when parsing command output, it is acceptable to use fixed patterns. But where the pattern is likely to vary, such as when it depends on local conventions like host and user names, and where the pattern is used multiple times, it should be compiled into a global variable using the
No strict checking. Code should always be written with strict checking enabled. Variables should always be predeclared with in a
No comments. Completely inexcusable. Subroutines should always be commented with a basic explanation of their function, a brief description of the arguments they expect to receive, and their range of return values. Variable declarations should include a brief note on their intended purposes. Code blocks should always include a short description of their function and pattern matches should include an comment containing an example or a description of a valid match.
Consequently, it took me far longer than expected to work out what the code was doing, to trace through all the global variables, and discover that the problem I was trying to trace lay in a buggy pattern match that made incorrect assumptions about the names of the machines. Bah.
Sloppy indentation. Completely unacceptable. Most modern editors provide syntax aware indentation. If you're working with an editor that doesn't indent correctly, then upgrade to one that does.
Poor line wrapping. Lines should be wrapped at around 72 characters, not because people still use fixed size terminals but because very long lines are much harder to read and debug.
Limited use of subroutines. Code should always be chopped up into reasonable sized logical subroutines. This should be done even if the code is only used once, because it makes the code much easier to debug using the next command. It also makes it possible to scope variables.
Poor variable scoping. Variables should be declared with the most limited scope possible, even if this increases the number of arguments that need to be passed in subroutine calls. Global variables should be used extremely sparingly and magic variables such as
$_ should be eschewed when writing production code.Hardwiring of patterns. In cases where patterns are unlikely to vary, e.g. when parsing command output, it is acceptable to use fixed patterns. But where the pattern is likely to vary, such as when it depends on local conventions like host and user names, and where the pattern is used multiple times, it should be compiled into a global variable using the
qr// operator in order to improve portability.No strict checking. Code should always be written with strict checking enabled. Variables should always be predeclared with in a
my() call at the start of each code block and this should be used as an opportunity to include a comment that describes the purpose of each variable.No comments. Completely inexcusable. Subroutines should always be commented with a basic explanation of their function, a brief description of the arguments they expect to receive, and their range of return values. Variable declarations should include a brief note on their intended purposes. Code blocks should always include a short description of their function and pattern matches should include an comment containing an example or a description of a valid match.
Consequently, it took me far longer than expected to work out what the code was doing, to trace through all the global variables, and discover that the problem I was trying to trace lay in a buggy pattern match that made incorrect assumptions about the names of the machines. Bah.
