Richard Fussenegger

Richard Fussenegger

Contents

PHP RFC: Class Naming

Introduction

The PHP coding standard does not cover how class names should be written. This leads to friction within the userland community that is now largely following the standard recommendation PSR-1. Extending our current coding standard to cover edge cases about abbreviations and acronyms/initialisms would resolve any future discussion.

Proposal

Extend the coding standard to explicitly specify how abbreviations and acronyms/initialisms are to be handled when writing user-level class names. The current rule is:

Classes should be given descriptive names. Avoid using abbreviations where possible. Each word in the class name should start with a capital letter, without underscore delimiters (CamelCaps starting with a capital letter). The class name should be prefixed with the name of the 'parent set' (e.g. the name of the extension)::

Good:
'Curl'
'FooBar'

Bad:
'foobar'
'foo_bar'

CODING_STANDARD

While it is stated that abbreviations should be avoided, it is silent on what to do if they are used; especially in the case of acronyms/initialisms. There are essentially three choices possible now:

  1. PascalCase except Acronyms/Initialisms — which is how the majority of user-level class names are written, and it matches the approach of many other programming languages.
  2. Always PascalCase — which is basically what PSR-1 defines, however, it would make most of the currently existing user-level class names invalid.
  3. Do Nothing — which of course automatically means that any approach is allowed, and the community discussions around this topic will continue.
IMPORTANT!

Regardless of the outcome of this RFC, existing user-level class names are not required to be changed. Although it would be possible (class names are case-insensitive). The reason why renaming is not proposed is simple: this RFC would most probably fail because too many people are against such purely cosmetic changes.

IMPORTANT!

PascalCase except Acronyms/Initialisms

Class names should be descriptive nouns in PascalCase and as short as possible. Each word in the class name should start with a capital letter, without underscore delimiters. The class name should be prefixed with the name of the “parent set” (e.g. the name of the extension) if no namespaces are used. Abbreviations and acronyms as well as initialisms should be avoided wherever possible, unless they are much more widely used than the long form (e.g. HTTP or URL). Abbreviations start with a capital letter followed by lowercase letters, whereas acronyms and initialisms are written according to their standard notation. Usage of acronyms and initialisms is not allowed if they are not widely adopted and recognized as such.

Good:
'Curl'
'CurlResponse'
'HTTPStatusCode'
'URL'
'BTreeMap' (B-tree Map)
'Id' (Identifier)
'ID' (Identity Document)
'Char' (Character)
'Intl' (Internationalization)
'Radar' (Radio Detecting and Ranging)

Bad:
'curl'
'curl_response'
'HttpStatusCode'
'Url'
'BtreeMap'
'ID' (Identifier)
'CHAR'
'INTL'
'RADAR' (Radio Detecting and Ranging)

GitHub PR #2552

Always PascalCase

Class names should be descriptive nouns in PascalCase and as short as possible. Each word in the class name should start with a capital letter, without underscore delimiters. The class name should be prefixed with the name of the “parent set” (e.g. the name of the extension) if no namespaces are used. Abbreviations and acronyms as well as initialisms should be avoided wherever possible, unless they are much more widely used than the long form (e.g. HTTP or URL). Abbreviations, acronyms, and initialisms follow the same letter-casing as any other word.

Good:
'Curl'
'CurlResponse'
'HttpStatusCode'
'Url'
'BTreeMap' (B-tree Map)
'Id' (Identifier and Identity Document)
'Char' (Character)
'Intl' (Internationalization)
'Radar' (Radio Detecting and Ranging)

Bad:
'curl'
'curl_response'
'HTTPStatusCode'
'URL'
'BtreeMap'
'ID'
'CHAR'
'INTL'
'RADAR'

GitHub PR #2553

Backward Incompatible Changes

None, we only update the coding standards for the future.

Future Scope

  • Update existing user-level class names according to the outcome of this RFC.

Patches and Tests

References

Votes

An option needs 50%+1 votes to win

Should we update the coding standard? (65.4% approved)
User Vote
aeoris Yes
ajf Yes
ashnazg Yes
bwoebi No
colinodell Yes
danack No
derick No
emir Yes
galvao Yes
guilhermeblanco Yes
heiglandreas No
hywan Yes
jhdxr No
kalle No
kelunik No
kguest Yes
laruence Yes
mbeccati Yes
narf Yes
ocramius Yes
omars Yes
peehaa No
remi No
sammyk Yes
stas Yes
zeev Yes
What class naming style should we use? (100% approved)
User Vote
aeoris Always PascalCase
ashnazg Always PascalCase
bwoebi PascalCase except Acronyms
cmb Always PascalCase
colinodell Always PascalCase
danack Always PascalCase
derick PascalCase except Acronyms
emir PascalCase except Acronyms
galvao PascalCase except Acronyms
guilhermeblanco PascalCase except Acronyms
heiglandreas PascalCase except Acronyms
hywan Always PascalCase
kalle Always PascalCase
kelunik PascalCase except Acronyms
kguest PascalCase except Acronyms
laruence PascalCase except Acronyms
mbeccati PascalCase except Acronyms
narf PascalCase except Acronyms
ocramius PascalCase except Acronyms
omars PascalCase except Acronyms
pollita PascalCase except Acronyms
sammyk Always PascalCase
stas PascalCase except Acronyms
subjective Always PascalCase
yunosh Always PascalCase
zeev Always PascalCase