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 that are desired to be in the class name should be suffixed rather than prefixed, e.g. abstract class FooAbstract {}
    • such suffixing is not preferred, but neither is it outlawed

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.

Proposed Solution

Initial rules and guidelines:

  • no suffix for an Abstract or Interface class name is necessary, nor is it preferred
    • attempts to misuse abstract classes and interfaces in userspace code will be caught by PHP anyway
    • any extra naming is effectively just for code readers to shortcut/avoid reading the code documentation, which isn't a best practice to promote
  • 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)
  • 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
  • an “Interface” suffix should not be used at all, as usage of “interface PublishableInterface {}” as “class Publisher implements PublishableInterface {}” seems less readable.

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.1243526552.txt.gz · Last modified: 2017/09/22 13:28 (external edit)