docs/naming.txt

   1
   2 Naming
   3
   4 The classes in this library follow a few naming conventions, which may
   5 help you find the correct functionality more quickly.  Here they are:
   6
   7 All classes occupy the HTMLPurifier pseudo-namespace.
   8     This means that all classes are prefixed with HTMLPurifier_.  As such, all
   9     names under HTMLPurifier_ are reserved.  I recommend that you use the name
  10     HTMLPurifierX_YourName_ClassName, especially if you want to take advantage
  11     of HTMLPurifier_ConfigDef.
  12
  13 All classes correspond to their path if library/ was in the include path
  14     HTMLPurifier_AttrDef is located at HTMLPurifier/AttrDef.php; replace
  15     underscores with slashes and append .php and you'll have the location of
  16     the class.
  17
  18 Harness and Test are reserved class names for unit tests
  19     The suffix "Test" indicates that the class is a subclass of UnitTestCase
  20     (of the Simpletest library) and is testable. "Harness" indicates a subclass
  21     of UnitTestCase that is not meant to be run but to be extended into
  22     concrete test cases and contains custom test methods (i.e. assert*())
  23
  24 Class names do not necessarily represent inheritance hierarchies
  25     While we try to reflect inheritance in naming to some extent, it is not
  26     guaranteed (for instance, none of the classes inherit from HTMLPurifier,
  27     the base class).  However, all class files have the require_once
  28     declarations to whichever classes they are tightly coupled to.
  29
  30 Strategy has a meaning different from the Gang of Four pattern
  31     In Design Patterns, the Gang of Four describes a Strategy object as
  32     encapsulating an algorithm so that they can be switched at run-time.  While
  33     our strategies are indeed algorithms, they are not meant to be substituted:
  34     all must be present in order for proper functioning.
  35
  36 Abbreviations are avoided
  37     We try to avoid abbreviations as much as possible, but in some cases,
  38     abbreviated version is more readable than the full version. Here, we
  39     list common abbreviations:
  40         Attr(s) -> Attribute(s)
  41         Def -> Definition
  42
  43 Ambiguity concerning the definition of Def/Definition
  44     While a definition normally defines the structure/acceptable values of
  45     an entity, most of the definitions in this application also attempt
  46     to validate and fix the value.  I am unsure of a better name, as
  47     "Validator" would exclude fixing the value, "Fixer" doesn't invoke
  48     the proper image of "fixing" something, and "ValidatorFixer" is too long!
  49     Some other suggestions were "Handler", "Reference", "Check", "Fix",
  50     "Repair" and "Heal".
  51
  52 Transform not Transformer
  53     Transform is both a noun and a verb, and thus we define a "Transform" as
  54     something that "transforms," leaving "Transformer" (which sounds like an
  55     electrical device/robot toy).
  56