As a contrib developer, I learned how to write both core patches and contrib modules by reading core code.
Drupal 7 is highly consistent internally and provided many good examples to follow.
Drupal 8, due to its long development cycle full of refactorings, has chosen to do conversions gradually, and the result of this has been the loss of internal consistency. Inside the same class you can find different naming conventions, docblock standards, array notations (array() vs [], sometimes even in the same method). Not to mention deprecated code and different patterns applied to the same problems.
So, since there are now multiple ways of doing the same thing in core, I can no longer rely on core as a teaching tool. As a part of writing Commerce 2.x and reviewing contributor's patches, I've had to practise ask-Berdir-driven-development way too much. The DX impact is significant because of the increased cognitive load and frustration over things as simple and insignificant as "how do I load an entity" and "how do I document my getters".
I've already been yelled at for raising a seemingly insignificant issue too close to a release, but I truly believe this is important.
Some of the issues are already documented, or almost done (removal of deprecated code), some will need additional consensus but require no breaking changes. Let's see what we can do to improve this situation.
Issues:
#2471485: Standardize getter docblocks - standardize on "Gets" vs "Returns" in getter docblocks.
#2225347: [META] Replace calls to ENTITY_TYPE_load() and ENTITY_TYPE_load_multiple() with static method calls - finish killing entity_load(), this still comes up in contrib too often.
#2474151: Mark procedural wrappers in entity.inc as deprecated - actually mark entity_load() and friends as deprecated.
#1832630: [policy, then patch] Decide on coding standard for configuration keys of ConfigEntities - most of our config entites break our own coding standards.
#2346857: Set default property bundle_entity_type in EntityType to NULL Assigned to: yched - bundles should be used consistently
#2316171: [meta] Improve DX of entity defining (if you want a UI) - self-descriptive
Feel free to add your own.
Comments
Comment #1
bojanz CreditAttribution: bojanz commentedComment #2
bojanz CreditAttribution: bojanz commentedTim Plunkett suggested tracking the consistency related issues with its own tag.
Comment #3
andypostAdded #2346857: Set default property bundle_entity_type in EntityType to NULL
Comment #4
andypost#2316171: [meta] Improve DX of entity defining (if you want a UI)
Comment #5
bojanz CreditAttribution: bojanz commented@andypost
I would argue that #3 and #4 are not relevant, they are examples of things core can do better, but not things that are done differently in different places.
Comment #6
JeroenTComment #13
bojanz CreditAttribution: bojanz commented