Consistent naming convetions for tag names.
Fleshgrinder opened this issue · comments
The current ABNF for tag names is (ALPHA / "\") *(ALPHA / DIGIT / "\" / "-" / "_").
First obvious problem is that the dash collides with the planned vendor prefixes, see #95 as well.
Other than that there seems to be no real consistent naming convention for standard tag names. Most tags in userland (especially PHPUnit, Symfony, Doctrine, but many more) are camelCase or CamelCase. Re-introduction of @property-read and @property-write are currently discussed that would collide (again) with the planned vendor prefixes and would deviate from all other tag names that exist in the standard as of yet (see #15, #37, and #94 for comments regarding the consistency problem).
I propose to standardize only camelCase tag names, now and in the future.
I further propose* to use the newly planned specialization feature for the previously mentioned @property-read and @property-write annotations. This would result in @property:read and @property:write. Adoption would be easy because current implementations would only need to exchange the dash with the colon. The backwards compatibility break is widespread but not severe and the fix is trivial. We also have an example for the specialization usage in the standard, which is a good thing.
*) I do not think that it would be helpful to open yet another issue for this topic. We have to agree upon the conventions for tag names once and for all and this decision will also dictate how the @property specializations are handled.
Tag names are generally in snake_case, annotations are generally in CamelCase
For the record: there is officially no standard for that mentioned in the PSR itself because this is merely a convention. Tag names are case insensitive
This is however a problem in my opinion, because it is inconsistently implemented across the official tags. I know by now that you do not care so much about that, but I need to repeat myself that consistency is extremely important especially in PHP related stuff.
@Fleshgrinder I'm all about consistency, but you have the battle of existing support. Even if you change the new standard, you will still have to support the old, because there will be too many projects potentially using those standards.
Not sure how this PSR applies to FIG members. Whether FIG members will agree to update their documentation to conform to this PSR. Which would mean that you could have a problem with outside members not implementing the entire PSR.
I think that would not be as acceptable. I would like to implement this standard and follow it, even when I'm not part of FIG. Ultimately, if there are parts you don't agree with and you aren't a member of FIG, then you could just choose to not implement that part or change it to fit your convention.
I do think that with this standard, when it is finished, you could have a library that implements a parser for applications and tools to work off of. If that becomes the case, then I'm not sure how changes to the standard would apply.
I do also think that it is a really, bad idea to have docblock conventions, no matter how good it sounds. Having debates over conventions shouldn't hinder the current standard or at least I hope it doesn't.
Keeping backwards compatibility (BC) is a problem that applies all the time and many books and posts were written about this topic. However, keeping BC should not hinder you from fixing past mistakes. I have to repeat myself once more: look at PSR-2 where inconsistencies resulted in many parties complaining and complaining. Of course, someone will always complain, yes, but the amount of people complaining can be highly minimized if we are able to explain every decision with rational arguments; which are included in the PSR. In this case, both arguments are rational and valid. Nonetheless, not changing a potential problem because we are afraid of BC is imho a weak argument, especially if we know that we now have the possibility to fix it for the future. Adoption will take a long time and software should support old variations, but it paves the way for future software that does not require old behavior and makes it easier for such software. Do not forget that the actual casing will not affect any existing software and the same is true for future software, because tags are always case-insensitive. This is mainly about human readability and maybe custom userland regular expressions that try to parse something.
We currently only have two existing and very special tags that would be affected by a BC and those are @property-read and @property-write who are not even part of this PSR right now. Additionally, I do not even propose to change them to camelCase, I propose to use the specialization feature and consequently give users one standardized example of how to use specialization correctly. This change is trivial for software to support:
@property(?:-|:)(read|write)
Other tags are not affected, the change from @inhertidoc to @inheritDoc is only for consistency and does not affect any software and nobody is required to update their documentation to keep support. However, new software can apply it.
Do you know any other (possible) BCs?
If this needs to be pursued further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig