pear:rfc:pear2_class_naming

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
pear:rfc:pear2_class_naming [2009/02/10 21:42] – start on specific RFC examples ashnazgpear:rfc:pear2_class_naming [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 3: Line 3:
 ==== Document Information ==== ==== Document Information ====
   * Title: PEAR2 Class Naming Conventions   * Title: PEAR2 Class Naming Conventions
-  * Version: 0.1.0 +  * Version: 1.0.0 
-  * Status: Draft+  * Status: Ratified
   * Type: Informative Document   * Type: Informative Document
   * Wiki link:  http://wiki.php.net/pear/rfc/PEAR2_Class_Naming   * Wiki link:  http://wiki.php.net/pear/rfc/PEAR2_Class_Naming
 +  * Last Updated:  September 20th, 2009
 +  * Passed:  September 20th, 2009
 +
 +This RFC has been incorporated into the PEAR2 Standards ([[pear/rfc/pear2_standards]]).
  
 ==== Author(s) Information ==== ==== Author(s) Information ====
   * Name:  Chuck Burgess   * Name:  Chuck Burgess
-  * Name:  (second author needed)+  * Name:  Brett Bieber
   * Email: [[pear-group@php.net]]   * Email: [[pear-group@php.net]]
  
Line 17: Line 21:
  
 ==== Discussion List ==== ==== Discussion List ====
-   * Currently only pear-group; future is pear-dev[[http://news.php.net/php.pear.dev]]+This RFC is currently being discussed only by pear-group; future discussion will occur on pear-dev[[http://news.php.net/php.pear.dev]]
 + 
 +This RFC's content is also being influenced by the new PHP Standards group [[http://news.php.net/php.standards]].
  
 ===== Introduction ===== ===== Introduction =====
Line 30: Line 36:
  
 New guidelines for PEAR2: New guidelines for PEAR2:
-  * syntax/scope hints that are desired to be in the class name should be suffixed rather than prefixed, e.g. abstract class FooAbstract {} +  * syntax/scope hints in the class name must be suffixed rather than prefixed, e.g. abstract class FooAbstract {} 
-    * such suffixing is not preferredbut neither is it outlawed+    * such suffixing is required for abstract classes and interfacesfor additional clarity to non-native English readers [4]
  
 ===== Issues ===== ===== Issues =====
-A debate was spurred by the use of actual classes whose names, once namespaces removes their Several_Prefix_Layers_ from the name, will be just "Abstract" or "Interface" [2].  This prompted some discussion around various forms of "Hungarian Notation" in class naming, particularly for Abstract and Interface classes.  Part of this RFC addresses the PEAR Group's feelings regarding such naming style.+A debate was originally spurred by the use of actual classes whose names, once namespaces removes their Several_Prefix_Layers_ from the name, will be just "Abstract" or "Interface" [2].  This prompted some discussion around various forms of "Hungarian Notation" in class naming, particularly for Abstract and Interface classes.  Part of this RFC addresses the justification for requiring such naming style [4].
  
 ===== Proposed Solution ===== ===== Proposed Solution =====
 +
 Initial rules and guidelines: Initial rules and guidelines:
-  * no suffix for an Abstract or Interface class name is necessary, nor is it preferred +  * suffix for an Abstract or Interface class name is required 
-    * attempts to misuse abstract classes and interfaces in userspace code will be caught by PHP anyway +    * the extra naming is more legible to non-native English speakers [4] 
-    * any extra naming is effectively just for code readers to shortcut/avoid reading the code documentation, which isn't a best practice to promote +  * the suffix should be a full legible word, not a cryptic letter/abbreviation (e.g. FooAbst, FooA)
-  * any extra naming should be a full legible word, not a cryptic letter/abbreviation (e.g. FooAbst, FooA)+
     * this follows other well-known conventions (e.g. Java)     * this follows other well-known conventions (e.g. Java)
-  * an "Abstract" suffix is tolerable, e.g. abstract class FooAbstract {}, though neither necessary nor preferred + 
-    * having it suffixed makes it work better with IDE's autocompletion... otherwise, you'll always find yourself typing the full "Abstract" word just to reach the next character in the class name +The only exception to the Interface suffix requirement is the base package exception, which must be named simply "Exception". [3] 
-  * an "Interface" suffix should not be used at all, as usage of "interface PublishableInterface {}" as "class Publisher implements PublishableInterface {}" seems less readable.+ 
 +One benefit of the suffix rather than a prefix is in alphabetical-based visual listing of classes Using prefixes would result in all unrelated abstract classes being listed togther... the same result would apply to all unrelated intefaces.
  
 ===== Examples ===== ===== Examples =====
 +Here are some real-life examples gleaned from PEAR1 packages
 +
   * Demonstrating the inherited PEAR1 naming rules   * Demonstrating the inherited PEAR1 naming rules
     * "class Text_Diff" in /Text/Diff.php becomes "class Diff"     * "class Text_Diff" in /Text/Diff.php becomes "class Diff"
Line 53: Line 62:
     * "class Auth_PrefManager" in /Auth_PrefManager/PrefManager.php becomes "class PrefManager"     * "class Auth_PrefManager" in /Auth_PrefManager/PrefManager.php becomes "class PrefManager"
     * "class Services_Amazon_SQS" in Services_Amazon_SQS/Services/Amazon/SQS.php becomes "class SQS"     * "class Services_Amazon_SQS" in Services_Amazon_SQS/Services/Amazon/SQS.php becomes "class SQS"
 +
   * Demonstrating the new rules proposed by this RFC   * Demonstrating the new rules proposed by this RFC
-    * "interface Testing_DocTest_RunnerInterface" in Testing/DocTest/RunnerInterface.php becomes "interface Runner", or perhaps "interface Runnable" +    * "abstract class PHP_CodeSniffer_Standards_AbstractPatternSniff" in PHP_CodeSniffer/CodeSniffer/Standards/AbstractPatternSniff.php becomes "abstract class PatternSniffAbstract" 
-    +    * "interface Testing_DocTest_RunnerInterface" in Testing/DocTest/RunnerInterface.php becomes "interface RunnerInterface", or perhaps "interface RunnableInterface   
  
 ===== References ===== ===== References =====
   * [1]  PEAR1 Coding Standards for Class Naming -- [[http://pear.php.net/manual/en/standards.naming.php]]   * [1]  PEAR1 Coding Standards for Class Naming -- [[http://pear.php.net/manual/en/standards.naming.php]]
-  * [2]  [[Weierophinney]]'s original post about potential naming conflicts once Namespaces arrive -- [[http://weierophinney.net/matthew/archives/181-Migrating-OOP-Libraries-and-Frameworks-to-PHP-5.3.html]] +  * [2]  [[weierophinney]]'s original post about potential naming conflicts once Namespaces arrive -- [[http://weierophinney.net/matthew/archives/181-Migrating-OOP-Libraries-and-Frameworks-to-PHP-5.3.html]] 
 +  * [3]  PHP Standards Group's first meeting decisions, from 2009 php|tek -- [[http://news.php.net/php.standards/2]] 
 +  * [4]  [[weierophinney]]'s points on choosing Hungarian Notation, from the Standards meeting -- [[http://news.php.net/php.standards/22]]
pear/rfc/pear2_class_naming.1234302151.txt.gz · Last modified: 2017/09/22 13:28 (external edit)