From 76f2e4d371eea881a4be7c6ceacbe9857336c251 Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Sun, 6 Aug 2006 17:45:36 +0000 Subject: [PATCH] Commit naming conventions document. git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@176 48356398-32a2-884e-a903-53898d9a118a --- docs/naming.txt | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/naming.txt diff --git a/docs/naming.txt b/docs/naming.txt new file mode 100644 index 00000000..210178b1 --- /dev/null +++ b/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). +