[MODM-3] API design Created: 30/Apr/10  Updated: 09/Jun/10  Resolved: 30/Apr/10

Status: Resolved
Project: Doctrine MongoDB ODM
Component/s: None
Affects Version/s: 1.0.0ALPHA1
Fix Version/s: 1.0.0ALPHA1

Type: Improvement Priority: Minor
Reporter: Roman S. Borschel Assignee: Jonathan H. Wage
Resolution: Fixed Votes: 0
Labels: None


 Description   

I know I am nit-picky, I'm really just trying to help, but I think methods like save() that were recently added are just API bloat since all it does is persist + flush. The naming is also confusing, having both save and persist. If you really want to add a method to the public API to exchange 2 lines in user code against 1 line, then at least a more descriptive name would be better, like persistAndFlush().

API design is difficult, don't take it too lightly (thats what php did, heh)



 Comments   
Comment by Roman S. Borschel [ 30/Apr/10 ]

I think it just really helps ease of use if we keep the different APIs as similar as possible. Of course each can have their own methods, classes etc. We should just not overload the same names with completely different meanings in the different APIs.

Concerning this example, it just doesnt look very streamlined if there are such minor extra methods like save/persistAndFlush that you don't have in the other APIs and are neither mongo-specific (mongo-specific methods are fine!). Of course we don't want to fit the same API on all these projects, they should just not be too different in weird ways, like additional non-project-specific convenience methods that are available in one project but not in the other.

I hope I explained that well. It's just about a polished API feeling when using the different Doctrine projects.

Comment by Jonathan H. Wage [ 30/Apr/10 ]

I had the same thought when I was adding it and I wobbled back and fourth. Now that you say this I agree we should remove it.

Generated at Wed Nov 26 14:20:29 UTC 2014 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.