pear:rfc:pear2_class_naming

This is an old revision of the document!


Summary

Information

Document Information

Author(s) Information

  • This RFC is under the BSD License

Discussion List

This RFC is currently being discussed only by pear-group; future discussion will occur on pear-devhttp://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

With the introduction of namespaces in PHP 5.3, the PEAR1 rule of Package_Subpackage_ClassName naming (for creating pseudo-namespacing) is no longer necessary. Package naming rules will be set by the PEAR2_Naming_Standards RFC, whereas class naming rules are addressed here in this RFC.

The naming of individual classes retains these PEAR1 rules [1]:

  • Start with capital letter, e.g. class Foo {}
  • CamelCase for multi-worded class names, e.g. class FooBarBaz {}
  • Abbreviations only start with capital letter, e.g. class MrClean {}
  • Acronyms should be fully capitalized, e.g. class PEARTree {}

New guidelines for PEAR2:

  • syntax/scope hints in the class name must be suffixed rather than prefixed, e.g. abstract class FooAbstract {}
    • such suffixing is required for abstract classes and interfaces, for additional clarity to non-native English readers

Issues

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

Initial rules and guidelines:

  • a suffix for an Abstract or Interface class name is required
    • the extra naming is more legible to non-native English speakers [4]
  • the suffix should be a full legible word, not a cryptic letter/abbreviation (e.g. FooAbst, FooA)
    • this follows other well-known conventions (e.g. Java)

Examples

Here are some real-life examples gleaned from PEAR1 packages

  • Demonstrating the inherited PEAR1 naming rules
    • “class Text_Diff” in /Text/Diff.php becomes “class Diff”
    • “class DB_DataObject” in /DB_DataObject/DataObject.php becomes “class DataObject”
    • “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”
  • Demonstrating the new rules proposed by this RFC
    • “interface Testing_DocTest_RunnerInterface” in Testing/DocTest/RunnerInterface.php becomes “interface Runner”, or perhaps “interface Runnable”

References

pear/rfc/pear2_class_naming.1243527416.txt.gz · Last modified: 2017/09/22 13:28 (external edit)