Good APIs Are Transparent In Their Expectations And Dependencies
Posted May 9, 2012 at 9:38 AM by Ben Nadel
- Separate application logic [from event logic].
- Don't pass the Event object around.
In the explanation for the second rule, Zakas has a sentence that seems obvious at first; but, the more I think about it, the more profound it becomes:
Good APIs are transparent in their expectations and dependencies... (Page 79 of 205)
He brings this up in the context of event handling because he argues that the Event object should never be passed around. Since the Event object may have dozens of properties, defining the Event object as a method dependency (ie. argument / parameter) doesn't really provide any insight into what properties of the Event object will be used.
If you need to access, for example, the clientX and clientY properties of the event, simply extract those from the Event object and pass them into the necessary method. This makes it completely clear what data is required by the method and creates a transparent API.
Misko Hevery (Agile Coach at Google) talks about this approach in several of his Google Tech Talks. He explains that, from a Testing standpoint, passing around only the bare minimum of what is needed creates code that is much more easily tested. And, he argues, that code that is easily tested will also be code that is much better architected.
I bring this up only as a reality-check for myself: as I am architecting my code, I should always be asking myself if I can pass less data - if I can find a way to make my methods more cohesive and more transparent.
- Wanted: Full-Time ColdFusion Developer at Intoria Internet Architects
- Cold Fusion Senior Developer at Edge Information Management
- Back-End Web Developer-Information Technologist at Michigan State University
- ColdFusion Developer at Nonfat Media
- Mid-to-Senior Level Web Application Developer at SiteVision, Inc.
In The Pragmatic Programmer, they relate this to The law of Demeter.
Briefly, any object should know as little about the outside world as possible (e.g. it shouldn't need to know about the many methods and properties of the 'event' object when it really only needs to get a single property from it.
Would you recommend the maintainable js book?
Thanks for the link. I've been hearing a lot about the Law of Demeter (LoD) lately with all my reading about OOP (Object Oriented Programming). Especially when dependency injection (DI) is involved.
Lots of very interesting points of view! Still trying to wrap my head around it all and bring it together into one cohesive picture. I think my doing the "Object Calisthenics" is going to help. I gotta get another one of those started ASAP.
The latter half - automation - is something I personally need a LOT Of help with. As such, the book was a good dose of reality for me who typically rocks FTP or git Push/Pull to deploy code.
Take a look at the book Table of Contents to get a sense of how it might apply to you.
on the same line of thinking, it just seems more logical, to 'tell not ask' the object as to me it makes the object more modular when it only knows how to do what you tell it, and more direct to use since you can't ask it anything, *you* have to know what it does before using it and that should be covered in the api i.e. which methods are public - so everything becomes more like a one way conversation with each object telling the other what to do instead of asking, and it's a lot like a good business structure or the army where the person in charge tells their underling what to do, and they just do it if they can or pass it on to one of their underlings. lol.
can you provide a link that goes into more details about 'Object Calisthenics'