I have been working on several complex Drupal 7/Drupal Commerce projects over the last 16+ months and I have consistently hit a wall with fundamental problems using entities, loading, referencing, and "hydrating" entities.
Has anyone else felt my pain and can you provide recommendations on books or ANY documentation other that the poor excuse for documentation available in both the api.drupal.org or the documentation tree?
This could be out of exhaustion but, having been exposed to the EntityFieldQuery(), entity_load() design pattern for entities in Drupal 7 I can with confidence say that the current core design needs some serious leveling. The layers of abstraction that have been added don't make the process of loading an entity easier but more difficult.
Add to the problem that the layers of abstraction that are not 100% object oriented I can't actually trace the objects or methods because Drupal uses array-based registries and object structures. And don't get me started on the ctools object/method registries that are built at runtime.
This is seriously not workable.
Anyone have any recommendations to easy my pain?

Comments
I've run into lots of issues
I've run into lots of issues with entity API with the API not feeling, well, "finished." Once you accept that and realize that you'll have to build on top of that (and accept some help from the Entity API module) you might be surprised what you can accomplish and still do things "the drupal way."
I don't have alot of time to go into details at the moment, but I'm planning to do some how to articles and guides soon on our blog.
Greatly appreciated
Any insight would be greatly appreciated, I'm not saying I don't understand the entity API with the controller, models, and event registry (aka hook_info()). It is when I start to leverage community modules that embrace and extend the entity API. That's where I run into issue, either the module writer's understanding or implementation is a little off, or it is a mix of Entity API, ctools hooks, and field API calls.
For example, I'm trying to add a customer profile to the registration form, add a submit hook to the submit event stack and save the submitted field values into a newly created customer profile, attached to the newly created user account.
Technically the Address entity is several layers removed from the customer profile entity.
user
- address book
-- customer profile
--- address field
If everything worked as expected a customer profile (with additional fields) and the address field would render when it is attached to the registration form and form state. Sadly the field events (such as changing the country) don't fire or connect correctly to sibling state fields. The object itself isn't a fully qualified nor loads all of it's inherited fields or events.
I guess I'll need to hunt around in all of the modules to extended controller classes for the entities instead of attempting to load one or more entities using EntityFieldQuery().
Robert Foley Jr
Solutions Architect
http://www.robertfoleyjr.com
It sounds like most of the
It sounds like most of the problem that you're having is related to displaying the form for an entity in a different place. That is definitely on of the hard parts, separating forms from entities. At least commerce has separated their forms from page callbacks so you are that much closer. In a pinch building your own forms and assigning those form values to the entity and it's field during submit can help with those custom forms.
So I hacked a solution, sort of.
So I spent almost a week on getting the entities to instantiate and set values for each. And I successfully got the entities to save during events like registration, update user account, etc.
But man, was it truly painful and the solution is a garbled mess of field instances, form_state clobbering, entity loading, and field value setting.
There has to be a better way?
Robert Foley Jr
Solutions Architect
http://www.robertfoleyjr.com