Class Naming View as Markdown

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.

Proposed Voting Choices

Simple 50%+1 majority vote:

Vote: Should we update the coding standard? — Yes: 17 · No: 9 (closed)

Vote: What class naming style should we use? — PascalCase except Acronyms: 15 · Always PascalCase: 11 (closed)

Patches and Tests

• GitHub PR #2552: PascalCase except Acronyms
• GitHub PR #2553: Always PascalCase

References

• Internals Discussion
• Internals Pre-Discussion