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/05/28 15:29] – add reference to new PHP Standards group 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 32: 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 preferred, but neither is it outlawed+    * such suffixing is required for abstract classes and interfaces, for 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 +  * a 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 =====
Line 59: Line 64:
  
   * 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.1243524587.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools