This is an old revision of the document!
Summary
Information
Document Information
- Title: PEAR2 Class Naming Conventions
- Version: 0.1.0
- Status: Draft
- Type: Informative Document
Author(s) Information
- Name: Chuck Burgess
- Name: (second author needed)
- Email: pear-group@php.net
Legal Information
- This RFC is under the BSD License
Discussion List
- Currently only pear-group; future is pear-devhttp://news.php.net/php.pear.dev
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:
- 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” [1]. 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.
References
- [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