Naming Conventions
Filed under Development
The classes in this library follow a few naming conventions,
which may help you find the correct functionality more quickly. Here
they are:
- All classes occupy the HTMLPurifier pseudo-namespace.
- This means that all classes are prefixed with HTMLPurifier_.
As such, all names under HTMLPurifier_ are reserved. I recommend that
you use the name HTMLPurifierX_YourName_ClassName, especially if you
want to take advantage of HTMLPurifier_ConfigDef.
- All classes correspond to their path if library/ was in the
include path
- HTMLPurifier_AttrDef is located at HTMLPurifier/AttrDef.php;
replace underscores with slashes and append .php and you'll have the
location of the class.
- Harness and Test are reserved class names for unit tests
- The suffix
Test
indicates that the class is a
subclass of UnitTestCase (of the Simpletest library) and is testable.
"Harness" indicates a subclass of UnitTestCase that is not meant to be
run but to be extended into concrete test cases and contains custom
test methods (i.e. assert*())
- Class names do not necessarily represent inheritance
hierarchies
- While we try to reflect inheritance in naming to some extent,
it is not guaranteed (for instance, none of the classes inherit from
HTMLPurifier, the base class). However, all class files have the
require_once declarations to whichever classes they are tightly coupled
to.
- Strategy has a meaning different from the Gang of Four pattern
- In Design Patterns, the Gang of Four describes a Strategy
object as encapsulating an algorithm so that they can be switched at
run-time. While our strategies are indeed algorithms, they are not
meant to be substituted: all must be present in order for proper
functioning.
- Abbreviations are avoided
- We try to avoid abbreviations as much as possible, but in some
cases, abbreviated version is more readable than the full version.
Here, we list common abbreviations:
- Attr to Attributes (note that it is plural, i.e.
$attr
= array()
)
- Def to Definition
$ret
is the value to be returned in a function
- Ambiguity concerning the definition of Def/Definition
- While a definition normally defines the structure/acceptable
values of an entity, most of the definitions in this application also
attempt to validate and fix the value. I am unsure of a better name, as
"Validator" would exclude fixing the value, "Fixer" doesn't invoke the
proper image of "fixing" something, and "ValidatorFixer" is too long!
Some other suggestions were "Handler", "Reference", "Check", "Fix",
"Repair" and "Heal".
- Transform not Transformer
- Transform is both a noun and a verb, and thus we define a
"Transform" as something that "transforms," leaving "Transformer"
(which sounds like an electrical device/robot toy).