#! /usr/bin/perlcritic #? #? NAME #? .perlcriticrc - configuration for Perl::Critic for O-Saft #? #? SYNOPSIS #? perlcritic ... #? #? DESCRIPTION #? This file contains the configuration for Perl::Critic, perlcritic. #? The settings are explained, why they are ENABLED or DISABLED. #? #? ################################################################### #? FIXME: this file is a first attempt, not yet completed. #? ################################################################### #? #? EXAMPLES #? # the usual way #? perlcritic #? #? # print policy for each message #? perlcritic --verbose 8 #? #? # print full description for each message #? perlcritic --verbose 10 #? #? # check for a single policy (Subroutines::RequireFinalReturn) #? perlcritic --single-policy Subroutines::RequireFinalReturn #? perlcritic --only --include Subroutines::RequireFinalReturn #? #? # just get a statistic for severity 4 and 5 #? perlcritic --severity 4 --statistics-only #? #? # get a a quick overview for violations of severity 4 and 5 #? perlcritic *.pl *.pm --severity 4 --count #? #? LIMITATIONS #? Do not use perlcritic with an directory as parameter in the development #? directory as there are too much matching files (i.e. SCCS/*) which may #? cause problems. Use list of files instead: *.pl *.pm Net/*.pm #? #? SEE ALSO #? contrib/critic.sh #? #? VERSION #? @(#) .perlcriticrc 1.15 22/11/06 12:22:40 # #? AUTHOR #? 06-apr-16 Achim Hoffmann #? # ----------------------------------------------------------------------------- # global options severity = 5 # will change to 4 o 3 later verbose = 8 # always want to see the policy name #program-extensions '.pl .pm' # does not work as described by Perl::Critic :-/ # theme = o-saft [ControlStructures::ProhibitPostfixControls] allow = if unless #allow = foreach # as the severity is already 2, its okay to report foreach violations # Message # Postfix control "if" used at line ... # CHECK adapted # Postfix controls are used often to have the relevant code far left! [InputOutput::RequireCheckedClose] severity = 1 # Message # Return value of "close" ignored at line ... # CHECK DISABLED # For our purpose it's nice if the files is closed, but not necessary. # hence severity reduced to 1 #[InputOutput::RequireCheckedOpen] #[InputOutput::RequireCheckedSyscalls] [InputOutput::RequireBriefOpen] lines = 15 severity = 2 # Message # Close filehandles as soon as possible after opening them at line ... # CHECK adapted # Because we have more code until close, sometimes. # TODO: lines= seems not to work as descibed, produces false positives # therefore serverity is reduced [InputOutput::RequireEncodingWithUTF8Layer] # Message # I/O layer ":utf8" used at line # CHECK ENABLED # CHECK adapted # However ... # The description of Perl::Critic is mainly valid according input. But # Perl::Critic also complains for output and states, cite: # "For consistency's sake, this policy checks files opened for output # as well as input, For complete coverage it also checks `binmode()' # calls, where the direction the operation can not be determined." # This is wrong, as binmode() usually uses the common bare word file # handles like STDOUT, STDERR, STDIN undoublty. # Our code uses binmode() only for output, hence this check is a false # positive. As this check should be active for future changes, we mark # all our binmode() calls with a proper ## no critic . [InputOutput::ProhibitBacktickOperators] only_in_void_context = 1 # Message # Backtick operator used at line ... # CHECK ENABLED # Literal backticks are not used, but the qx() operator. Backticks are # used in void context, hence the restriction to only_in_void_context. [InputOutput::ProhibitBarewordFileHandles] [InputOutput::ProhibitTwoArgOpen] # Messages: # Bareword file handle opened at line ... # Two-argument "open" used at line ... # A bareword is a series of characters (like the FH) without quotes # around them, or without a sigil in-front of them. They can be used in # some places, but in file-handles they are not recommended any more. # Recommendation # Always use lexical variables and always use 3-parameter for open. [-InputOutput::ProhibitExplicitStdin] # Message # Use "<>" or "" or a prompting module instead of "" at line ... # CHECK DISABLED # The reason why "*ARGV behaves like *STDIN" is described as # "is almost always what you want" sounds strange. # In our usage this is never the case, because we also may get data on # STDIN and have command line arguments. #[InputOutput::ProhibitInteractiveTest] #[InputOutput::ProhibitJoinedReadline] #[InputOutput::ProhibitOneArgSelect] [InputOutput::ProhibitOneArgSelect] # Message # One-argument "select" used at line ... # CHECK ENABLED # selectively disabled in souce with ## no critic .. #[InputOutput::ProhibitReadlineInForLoop] #[InputOutput::RequireBracedFileHandleWithPrint] [References::ProhibitDoubleSigils] # Message # Double-sigil dereference at line ... # CHECK ENABLED [Modules::ProhibitAutomaticExportation] # Message # Symbols are exported by default at line ... # CHECK ENABLED [Modules::RequireBarewordIncludes] severity = 3 # Message # "require" statement with library name as string at line ... # CHECK ENABLED # CHECK adapted # FIXME: O-Saft uses require like: require "o-saft-man.pm"; # which is necessary because the filename contains a - (dash), without # quotes Perl complains with: # Bareword "saft" not allowed while "strict subs" in use # # To get rid of this critic, the filename needs to be changed. That's # why we leave this violation but reduce the severity to 3. [RegularExpressions::ProhibitCaptureWithoutTest] [RegularExpressions::ProhibitUnusedCapture] # Messages # Capture variable used outside conditional at line ... # Only use a capturing group if you plan to use the captured value at line ... # CHECK ENABLED # NOTE: Perl::Critic has a lot of false negatives! [Modules::ProhibitExcessMainComplexity] # Message # Main code has high complexity score (NN) at line ... # CHECK ENABLED [Subroutines::ProhibitExcessComplexity] # Message # Subroutine "XXXX" with high complexity score (29) at line ... # CHECK ENABLED # TODO: CHECK adapted # Net::SSLinfo.pm max_mccabe = 45 [-Subroutines::ProhibitUnusedPrivateSubroutines] # Message # Private subroutine/method 'XXXX' declared but not used at line ... # CHECK DISABLED [-RegularExpressions::RequireDotMatchAnything] # Message # Regular expression without "/s" flag at line ... # CHECK DISABLED # cause we know about meta character . and /s modifier in RegEx ;-) [-RegularExpressions::RequireLineBoundaryMatching] # Message # Regular expression without "/m" flag at line ... # CHECK DISABLED # cause we use /m as needed [-RegularExpressions::RequireExtendedFormatting] # Message # Regular expression without "/x" flag at line ... # CHECK DISABLED # because we use /x as needed for human readability [Subroutines::ProhibitBuiltinHomonyms] # Message # Subroutine name is a homonym for builtin function XXXX at line ... # CHECK ENABLED [-Subroutines::ProhibitManyArgs] # Message # Too many arguments at line ... # CHECK DISABLED # because there are functions with more than 5 paramters # NOTE: this policy has no "allow" option but we need more than 5 # arguments, sometimes;hence disabled [-Subroutines::ProhibitSubroutinePrototypes] # Message # Subroutine prototypes used at line ... # CHECK DISABLED # Contrary to Perl::Critic we consider prototypes as useful, even if # the compile-time checks of Perl are not perfect, Perl may give some # hints. [Subroutines::RequireArgUnpacking] # Message # Always unpack @_ first at line ... # CHECK ENABLED [Subroutines::RequireFinalReturn] # Message # # CHECK ENABLED [-CodeLayout::RequireTidyCode] # Message # Code is not tidy at line 1, column 1. # CHECK DISABLED # TODO: tidy not yet used [-CodeLayout::ProhibitParensWithBuiltins] # Message # Builtin function called with parentheses at line ... # CHECK DISABLED # Contrary to BPB we think that all functions should use parentheses. # Continous use of parentheses makes third-party parsers happy. # However: we miss parentheses, mainly for print builtin function. [-CodeLayout::RequireTidyCode] # Message # Code is not tidy at line 1, column 1. # CHECK DISABLED # TODO: tidy not yet used [CodeLayout::ProhibitHardTabs] # CHECK ENABLED # there are leading tabs only, usually [CodeLayout::ProhibitTrailingWhitespace] # Message # Found "\N{SPACE}" at the end of the line ... # CHECK ENABLED # We hate unecessary characters too ;-) [CodeLayout::RequireConsistentNewlines] # CHECK ENABLED [-Variables::ProhibitLocalVars] # Message # Variable declared as "local" at line ... # CHECK DISABLED # NOTE: Following this critism violates Variables::ProhibitReusedNames # we prefer to check for reused variables [Variables::ProhibitPackageVars] add_packages = Net::SSLinfo Net::SSLhello Net::SSLeay # Message # Package variable declared or used at line ... # CHECK adapted # Add our private modules, this leaves unwanted global variables to be # reported only. # Net::SSLeay is configured using its private variables. [Variables::ProhibitPunctuationVars] allow = $@ $! $? $0 $. $^O $\ # we make regular use of these variables as we know them;-) [Variables::RequireLocalizedPunctuationVars] allow = @ENV # Message # Magic variable "$ENV" should be assigned as "local" # CHECK adapted # @ENV must be changed globally (at least in o-saft.pl) # TODO: need to verify if @INC should be allowed too # Perl::Critic seems to be buggy as it does not honor the allow option # hence an annotation is used in o-saft.pl [Variables::ProhibitReusedNames] allow = $host $port $legacy $arg # Message # Reused variable name in lexical scope: ... # CHECK adapted # These variables are often used in subs, but also in main, hence # we allow them for reuse. [Variables::RequireInitializationForLocalVars] # Message # "local" variable not initialized at line ... # CHECK ENABLED [RegularExpressions::ProhibitCaptureWithoutTest] # Message # Capture variable used outside conditional at line ... # CHECK ENABLED # Workaround: disable selectively where appropriate with: #[RegularExpressions::ProhibitComplexRegexes] # Message # Split long regexps into smaller qr// chunks at line ... # FIXME: to be discussed # Workaround: disable selectively where appropriate with: #[ValuesAndExpressions::ProhibitConstantPragma] # Message # Pragma "constant" used at line ... # CHECK ENABLED [-ValuesAndExpressions::ProhibitEmptyQuotes] # Message # Quotes used with a string containing no non-whitespace characters at line ... # CHECK DISABLED # cause we consider following correct and useful: my $var = ''; # the recomended use of q{} looks too complex: my $var = q{}; [-ValuesAndExpressions::ProhibitNoisyQuotes] # Message # Quotes used with a noisy string at line ... (Severity: 2) # CHECK DISABLED # other people, other opinions: "," is better readable than qw(,) [ValuesAndExpressions::ProhibitEscapedCharacters] # Message # Numeric escapes in interpolated string at line ... # CHECK ENABLED [-ValuesAndExpressions::ProhibitImplicitNewlines] # Message # Literal line breaks in a string at line ... # CHECK DISABLED # yes, there are a lot of constructs using nwelines in texts, that's ok [ValuesAndExpressions::ProhibitMagicNumbers] allowed_values = 0..99 allowed_values = 443 # allowed_types = # constant_creator_subroutines = # FIXME: to be discussed # Workaround: disable selectively where appropriate with: ## no critic qw(ValuesAndExpressions::ProhibitMagicNumbers) # CHECK adapted # we use some integers [ValuesAndExpressions::ProhibitMismatchedOperators] # Message # Mismatched operator at line ... # CHECK ENABLED [ValuesAndExpressions::RequireNumberSeparators] min_value = 100_000 # severity is 2 # Message # # CHECK adapted # we use some integers [ValuesAndExpressions::RequireQuotedHeredocTerminator] # Message # Heredoc terminator must be quoted at line ... # CHECK ENABLED # Workaround: disable selectively where appropriate [-ValuesAndExpressions::RequireUpperCaseHeredocTerminator] # Message # Heredoc terminator not alphanumeric and upper-case at line ... # CHECK DISABLED # other people, other opinions [RegularExpressions::ProhibitUnusedCapture] # Message # Only use a capturing group if you plan to use the captured value at line ... # CHECK ENABLED #[RegularExpressions::ProhibitFixedStringMatches] # Message # Use 'eq' or hash instead of fixed-pattern regexps at line ... # FIXME: to be discussed # we often use something like: if (m/^$/) # which is hard to be expressed as a hash #[TestingAndDebugging::ProhibitNoStrict] # Message: # Stricture disabled at line ... # FIXME: to be discussed # i.g. we want this warning, but strict is also disabled in the code # for good reason, probably use ## no critic qw(TestingAndDebugging::ProhibitNoStrict) [TestingAndDebugging::ProhibitNoWarnings] severity = 2 # Message: # Warnings disabled at line # CHECK adapted # FIXME: to be discussed; for now severity reduced from 4 to 2 # i.g. we want this warning, but some warnings are also disabled in # the code for good reason, probably use ## no critic qw(TestingAndDebugging::ProhibitNoWarnings) [TestingAndDebugging::RequireUseStrict] # Message: # Code before strictures are enabled at line ... # Note: # This check produces false positives in module files, if there is no # "use strict" , but this is not necessary as long as the module is # executed itself. # Anyway, "use strict" and "use warnings" is added to modules too. [-BuiltinFunctions::ProhibitBooleanGrep] # Message # "grep" used in boolean context at line ... # "grep" used in void context at line ... # CHECK DISABLED # Perl::Critic is too noicy and may have false positives, see its own # description: # perlcritic --doc BuiltinFunctions::ProhibitBooleanGrep #[BuiltinFunctions::ProhibitStringyEval] # Message: # Expression form of "eval" at line 3117 # FIXME: to be discussed # This occour for eval("require ..."), so probably use ## no critic qw(BuiltinFunctions::ProhibitStringyEval) [-BuiltinFunctions::ProhibitSleepViaSelect] # Message: # "select" used to emulate "sleep" at line ... # BuiltinFunctions::ProhibitSleepViaSelect (Severity: 5) # Conway discourages the use of `select()' for performing non-integer # sleeps. Although documented in perlfunc, it's something that generally # requires the reader to read `perldoc -f select' to figure out what it # should be doing. Instead, Conway recommends that you use the # `Time::HiRes' module when you want to sleep. # # select undef, undef, undef, 0.25; # not ok # # use Time::HiRes; # sleep( 0.25 ); # ok # CHECK DISABLED # We do not wish to use too much external modules. select is used # several times in SSLhello.pm # FIXME: write a osaft_sleep() which hides the select, this way the # violation is printed only once. Then we can enable it again. [-BuiltinFunctions::RequireBlockGrep] # Message: # The expression forms of `grep' and `map' are awkward and hard to read. # CHECK DISABLED # other people, other opinions [BuiltinFunctions::ProhibitStringySplit] # Message: # String delimiter used with "split" at line ... # CHECK ENABLED [Miscellanea::ProhibitUnrestrictedNoCritic] # does not make sense to disable it, can even not be disabled :-/ [-Documentation::RequirePodSections] lib_sections = NAME | SYNOPSIS | DESCRIPTION | AUTHOR # Message: # Missing "OPTIONS" section in POD at line ... # CHECK DISABLED # cause we consider following correct and useful: my $last = ''; # Perl::Critic is uses a strange list of required sections in POD. # Also there is no possibility to disable Perl::Critic's required # sections, hence generally disabled. [-NamingConventions::ProhibitAmbiguousNames] # Message: # Ambiguously named variable "last" at line ... # CHECK DISABLED # cause we consider following correct and useful: my $last = ''; # Perl::Critic is too pedantic here as it is no problem at all with perl.