Indeed. I've acknowledged that in php.internals: Re: Casing of acronyms in class and method names. However doing so is out of scope for this RFC. I'm also not the appropriate person to rewrite the policies to give them a proper structure. I'm neither a technical writer, nor a native speaker of English.
----------
If this RFC is accepted, I'll make the proposed wording change to CODING_STANDARDS.md in php-src and append the relevant part of the RFC text to coding-standards-and-naming.rst in policies, so that it's properly accounted for when the policies in the policies repository are cleaned up as a follow-up to the policies RFC.
The two weeks of discussion are over now, the RFC didn't receive any substantial changes after the initial proposal, and neither was there any significant content-related feedback after the first few days.
As such, I plan to open the vote early next week without making further changes to the RFC text.
Not that my opinion counts for much, but I have to say I find this very odd.
Good class names:
Id // Identifier
ID // Identity Document
I understand the distinction you wish to make here, between an acronym
and abbreviation, but I think it's a meaningless distinction. In this
case, `Id` would be fine for "identifier", but "Identity Document"
should simply be `IdentityDocument`. Whilst the distinction may seem
meaningful to you, it certainly does not look that way to me; I think it
would be difficult to remember and explain to someone else. Perhaps the
tie breaker could be that it wouldn't be meaningful to an automated
style checker, either. That is, it would be difficult to enforce this
policy exception in any automated way. Why not just keep it simple and
consistent here, disallowing runs of multiple upper-case letters?
I have copied the example identifiers verbatim from the existing phrasing in CODING_STANDARDS.md and just moved them into the correct section according to the updated wording.
However 'ID' as-in 'Identity Document' should also be 'Id' with the updated policy, which I missed. Or rather it should not be abbreviated at all.
I've adjusted the examples [1], thank you for pointing this out!
The two weeks of discussion are over now, the RFC didn’t receive any substantial changes after the initial proposal, and neither was there any significant content-related feedback after the first few days.
As such, I plan to open the vote early next week without making further changes to the RFC text.
Best regards
Tim Düsterhus
Hi Tim,
Not that my opinion counts for much, but I have to say I find this very odd.
Good class names:
Id // Identifier
ID // Identity Document
I understand the distinction you wish to make here, between an acronym and abbreviation, but I think it’s a meaningless distinction. In this case, Id would be fine for “identifier”, but “Identity Document” should simply be IdentityDocument. Whilst the distinction may seem meaningful to you, it certainly does not look that way to me; I think it would be difficult to remember and explain to someone else. Perhaps the tie breaker could be that it wouldn’t be meaningful to an automated style checker, either. That is, it would be difficult to enforce this policy exception in any automated way. Why not just keep it simple and consistent here, disallowing runs of multiple upper-case letters?
Cheers,
Bilge
I was under the impression that this RFC was trying to solve exactly that, so I’m surprised to see that ID would be allowed.