Commit naming conventions document.

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@176 48356398-32a2-884e-a903-53898d9a118a

docs/naming.txt

@@ -0,0 +1,53 @@
+
+Naming
+
+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, and userspace extensions should
+    be registered in a different namespace (or the main namespace).
+
+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(s) -> Attribute(s)
+        Def -> Definition
+
+Ambiguity concerning the definition of 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!
+
+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).
+