Design Principles: "No occult side-effects"

[ErichBSchulz]

This could be yet another Design Principle (arising from @eileenmcnaughton's comment on #14)

ie:

• clear distinction between what is a pure CRUD "plumbing" operation and what is a complex "porcelain operation"
• ensuring side-effects are clearly documented, universally appropriate or explicitly configurable

[JoeMurray]

I don't find running together 'no occult side-effects' with a distinction between 'plumbing' and 'porcelain' helpful. There should be no occult side-effects in either case.

I'm having trouble seeing how to distinguish between business rules and side-effects, and how they could feasibly be documented, not that it wouldn't be great. So an event registration might prompt an email, trigger reminders to be scheduled, decrement the count on spaces available, do lots of stuff in accounting, change the amount to be raised on a Personal Campaign Page, create a contact, create an activity or two, create numerous entries in various log tables, etc.

[ErichBSchulz]

I've been reflecting on this @JoeMurray...

so the keyword seems to be "occult" - ie "it should do what it says on the box" ie side-effects must be documented

I can see how CRUD operation could legitimately fire hooks - so which ones need documenting (which [hopefully I can figure out soon how to do automatically or someone can tell me how)[http://civicrm.stackexchange.com/questions/17184/how-do-i-write-unit-tests-that-verify-a-hook-is-being-fired]

to me the basic CRUD operations imply a degree of atomicity so any secondary actions would surprise me (unless its documented of course)

all the things you list of Participation.Create would make complete sense to me for Participation.Register

similarly can imagine "business rules" that could apply to Event.Cancel that may be "side-effects" for Event.Delete too?? (ie refunds, email participants etc)