/ 
Perl-Critic-Grape-0.1.3
/ Perl::Critic::Policy::Variables::ProhibitExcessiveNames

NAME

Perl::Critic::Policy::Variables::ProhibitExcessiveNames - Use concise variable and subroutine names.

DESCRIPTION

Modules adhering to the Single Responsibility Principle should ensure that external context does not poison internal logic and clarity. Complex data should be represented structurally, not by using "universally unique names".

$thing_num                                             # no
$thing                                                 # yes

($thing_num, $thing_name, $thing_title)                # no
%thing, $thing{num}, $thing{name}, $thing{title}       # yes
$thing, $thing->num(), $thing->name(), $thing->title() # yes

$whatsit->translate_thing_from_json($thing_json)       # no
$whatsit->translate_motte_from_json($motte_json)       # no
$whatsit->from_json(thing=>$doc)                       # yes
$whatsit->from_json(motte=>$doc)                       # yes

Rules

  • No more than length fifteen, ever.

  • No more than three words, ever.

  • If a name uses more than one word, all words must have length greater than three.

    (See "CONFIGURATION")

Discussion

Lengthy, multiword names in code are indistinguishable from noise and, in general, a single line of code cannot reasonably represent a logical expression if each variable and function name is itself comprised of a large number of words. The issue is compounded by code style rules that pressure toward shorter line lengths, where a single function call and its parameters may span multiple lines when large names are in use.

Consider the Unix spell-checking dictionary which contains 48.5k words between length four and seven (inclusive). Taking the default configuration for this policy, there are more than 7.5 trillion combinations possible (42 bits, which exceeds Unix cksum as well as common non-cryptographic hash functions). The claim is not that all such combinations will be meaningful, but that names of this length become meaningless and, eventually, indistinguishable.

CONFIGURATION

The following control declarations that are considered violations.

  • length: The hard limit for maximum identifier length. Default fifteen.

  • words: The maximum number of words permitted. Default three.

  • smallest: The smallest permitted length for a single word in a multi-word identifier. Default four.

  • lpw: When non-zero, enforce a maximum length of lpw*N, where N is the number of words in the identifier. Default seven, so that two-word identifiers still fall under the default length limit. Note that the computed length is the entire identifier, including leading underscores that signify "private" names.

  • short: Names under this length are always allowed. Default six.

  • subs: Report excessive subroutine names. Default 1.

  • vars: Report excessive variable names. Default 1.

TODO

Approved short words

Some common prefix/suffixes should be configurable: has is new ok to

Abbreviations

In some cases, variables may contain sequences of uppercase letters that act as abbreviations: loadFromPNG, CSVwrite. While the underscore separation in such cases is clear (load_from_PNG, CSV_write), the camelcase variants may be indistinguishable (CSVwrite versus CSVWrite). It may also be that all are "wrong" and should instead be:

load(type=>'png',...)
write(type=>'csv',...)

But that mostly just moves the cheese since internal helpers would still be called writeCSV and loadPNG.

A configuration to support tail-only abbreviations may be appropriate: camelCaseThingAAA.