DrupalCon Prague 2013

Los aforismos del diseño de APIs

Larry Garfield  · 


HTML (pincha para descargar)



Extracto de la transcripción automática del vídeo realizada por YouTube.

thank everyone for coming the session is a frozen's of 80 KPI design if that's not what you're looking for it you're in the wrong room my name is Larry Garfield you may know me as Krell online if you want to make fun of me on Twitter during

the session that's where you do so I'm a senior architect at Palantir net or a web consulting firm in Chicago's focusing on Drupal for Drupal 8 signed the web services initiative lead and the trooper representative to the framework interoperability

group I'm an advisors at the Drupal Association and general purpose busybody who flies around and tells people what's wrong with their code that's kind of what I do let's start off by defining our terms a bit an API is an application programming

interface that is it is code intended for other code to use or people who write code but this is not something end-users see we're talking about the interface from code to code from coder to coder an aphorism is a concise statement containing a subjective

truth or observation cleverly and pitifully written cleverly and piffle II written that sounds like me so what we're talking about here are not hard blind rules they're more like guidelines well so what we're going to be doing is covering some

clever and pithy sayings about good code everyone's down for that sound a couple good plan all right and the first one we need to know learn the rules like a pro so you can break them like an artist this is not specific to programming but it applies here

for everything I'm about to say I guarantee you you will find an exception to it I can find an exception to it but these are still things you want to understand so that when you don't do it you have a good reason when you don't follow these guidelines

you understand why you would want to skip over them first off ever no Isaac Asimov most people I hope all right one of his books the gods themselves which I do recommend he posits that if there are multiple universes there are infinite universes basic idea

that book humans are contacted by aliens from a parallel dimension and plot happens and one of the characters observes you know if there's two universes why would they only be two there is probably a whole lot more parallel universes because really two

is the least likely number in the universe why would the only ever be two of something things could be unique there could be a whole lot of something why would there only be two and that means that in software if there's multiple possible implementations

of a given problem if there's multiple possible ways to deal with a certain situation then you should assume that there are an infinite number of possible implementations an infinite number of options so what does that mean at a very applied level who's

ever written an API in which you control options with constants with numbers couple people yeah don't do that so let's say we've got this code here load articles by status whatever and we passing one of these status constants publish your draft

and then you know look look those up from some mechanism you know views or career database query or whatever and then load them great and that's fine that's wonderful and great until you try to extend it or let someone else extend it and you go boom

because you didn't say anything about three but guaranteed someone's gonna want another status so how do you fix that makes that as a string there's a lot more strings than most likely to break bump into each other this is exactly what Drupal does

when it's doing it right and in some places there contributes that have done its the wrong way and have regretted it I think voting API is a good example they are early versions of voting API used constants for different modes and a whole bunch of voting

API extending modules came along and tried to either in constants and things exploded but wait Larry what about boolean x' aren't boolean is a to state isn't that a sense of something of which there's only ever - no because boolean czar not

a two-state value a boolean does not mean it's either/or it does not mean a or be a boolean is true or false a boolean is true or the absence of true a boolean is a single value is a value that is or is not it's a very subtle distinction but it's

something to keep in mind if you know that something could possibly be true or not that's a boolean if you could be using option A or option B and a and B are the only ones you can imagine ever existing you're wrong there's going to be a C and

someone's going to come up with it and you're gonna be stuck if you try using a boolean for that don't use boolean z' for modes good example here access is a boolean does user v have access to edit node 12 yes no that is the presence of access

or the absence of access that is not option A or option B access control which system decides the user has that access is in possibilities in triple7 you only had one access control callback but you could exchange it in Drupal 8 you could have many access

control callbacks and you have to account for potentially in infinite number of them corollary to this so what I like to call Garfield's law because I'm not egotistical at all one is a special case of many some of you may have heard me say this before

what does that mean let's take a look at node load multiple we've all used node load multiple at some point so in Drupal 6 this is how node load works vastly simplified we have you know you pass in a node ID we look up the base record out of the node

table and then we do extra stuff with it you know call hooks and so forth to make extra correct database queries and return that object and that's great and that's wonderful right up until you actually want to do the same thing to seven different nodes

at once and then oh good the only way to do it would be to load one table your load all the nodes base records and then call all of those hooks on each node individually and this is what you did in Drupal 6 with your own custom code you looped over than some

note IDs and did a note load on each one of them and ended up generating about 500 database queries this is known as the Select n + 1 problem it is also known as your database administrator hate you please don't make your database administrator hate you

this was fixed in Drupal 7 in Drupal 7 and in Drupal 8 any entity operation is innately a multiple operation node load is simply a simple wrapper around loading multiple nodes hook hook node load always assumes you're dealing with multiple nodes because

if you have an array of nodes the iteration you do is exactly the same if you have 150 or a hundred it's the exact same code which means you can treat one as a special case of many that greatly simplifies your code if you have to deal with you know I need

to may have one of these or I may have to do a multi operation that one case is always a subset of a multiple operation merge them which brings us to our first guideline n is the only number don't assume you know how many if something is going to be there

will be many of them many is a non defined number number to quote from Rasmus lead or founder of PHP fail fast fail cheap be lazy everyone here's lazy right if you're not then you're not doing a good job as a programmer good programmers make the

code debug for them because really why are you going to waste time debugging which you can make the Machine do it for you the whole point of having a computer is to make the computer do work for you so you don't have to don't plan for every eventuality

don't plan for everything that could possibly happen figure out how it's going to break in a way that's going to help you a good example of that Drupal 6 this is an excerpt from the theme function and you know go through the system and check alright

we're calling this theme key does the theme key exists if not all right just return null except that null in PHP gets cast to an empty string when you try to use it as a string which means if you have a typo and your theme function somewhere in one of

the four places you need to specify it you don't know in fact the system will not only not tell you it will actively try to keep you from finding out that you have a typo this is not good who has ever run for the problem where you know you're trying

to use a formatter in Drupal 6 and first who remembers developing a Drupal 6 ok so you always all had the experience of developing a formatter and having the crazy long name for the theme function you need for it and you're trying to write it and it just

doesn't show up and you have no idea why this is why I have lost tens of hours of my life to this problem that I will never get back whoever decided this is a good idea I blame you we fix this in Drupal 7 instead you know some of the logic change but now

if there's no hook found we log it which means if you get are getting a weird problem where you're trying to theme something it doesn't show up you can check the log and it'll tell you oh by the way this theme hooks not found and you can look

at it and go oh yeah I have a typo and you can fix this in about five to ten seconds instead of five to ten hours yes I've been there who's old enough to remember DOS this was a pretty useless error message wasn't it who's running to the Drupal

equivalent does anyone know what this even means a couple people what this means is somewhere in a forum array or a render array you have a string where you're supposed to have an array where I have no idea you have no idea and it's because that system

is recursive try debugging to find it you're still not gonna find it you're pretty much left with guessin check this is a very very bad thing this is why I'm big anonymous arrays are not a good data structure because they're in possible to

debug because all this error message tells you is by the way somewhere there's a bug in an array it's Drupal there's lots of a race this doesn't help me this might be an American joke code failures like voting in Chicago do people actually

get that joke here fail early fail often some people get it now yeah vote early vote off into the tradition Chicago the way to do that is you constrain your inputs and fail usefully what do we mean by that constraint inputs good api's are picky this is

an excerpt from the database system in Drupal 7 and Drupal 8 if you call this fields method and you pass in two arrays you're fine if you pass in something that is not an array this code does not know how to handle that so we specify it in the method call

[ ... ]

Nota: se han omitido las otras 5.390 palabras de la transcripción completa para cumplir con las normas de «uso razonable» de YouTube.