 So hi, my name is Joe Masty. This is bringing you X to your code These are my various things you can find me around What I do is a day job. I help companies to build awesome internal education programs Basically try to keep your employees happy and doing things that has nothing to do with this talk But I figured you should know what I do. I've been working at rails for five years so about five years ago, I Got sick of consulting and I ended up joining a company and I felt a little too qualified for the back-end job even though I actually come from a back-end history and so I applied for a UI job no real history in UI and they gave it to me, it's cool and I Just want to reinforce that I'm coming not from a designer perspective. I'm not a UX designer I'm not a UX developer. My my heart really lays way closer to the metal Our show of hands who here is like a UI front-endy person? Small small number of people you can raise both hands of your super UI. Yeah, who's like really back-end type of person? That's a majority of you. That's awesome because you are actually the target of this talk so When I joined this company as a as a UI developer I got a bunch of materials, you know, obviously learning rails new framework Also gave me a couple books to read and one of the books was by this guy Don Norman This guy started the user-centered design movement. He released a book in the the mid 1980s called the design of everyday things Anybody read this book? Yeah, surprisingly good number of hands, so it's like maybe like I'm quarter-ish If you've read this book, you know that you learn a lot about doors in this book I'm not the only one who thinks it's actually on wikipedia when I was I was looking things up. It's it's Authoritatively about doors But it's actually a really cool book. It's what it teaches you is that this door if you look at it the handles are totally identical on both sides, right and so They had to put a push label on there because everybody kept getting it wrong And I have this thing and I'm assuming that you probably do too where you've been doing this your entire life And you assume that you're really stupid And the book taught me that you're not really stupid. It's not your fault that that door sucks It's actually the guy who designed the door So that was a really important lesson for me And if you take nothing else away from this talk you can take away that somebody in the mid 1980s told you that it was Not your fault that doors suck So there's that But there's a lot of other good stuff in the book There are a lot of great lessons about usability it changed a lot about the way that I do software, but mostly in the context of Doing websites This is the first result that came up when I searched for really hard to use websites Apparently only like 20% of this is clickable and you can't tell which 20% the rest of it like moves around It's pretty bad, but as soon as we switch over to code There's really no mention of this usability stuff. This is not something that we pay attention to as back-end developers and I think that I know why that this is Yeah I've been doing this a while. I've been an engineer for for a fair amount of time and I believe in how wonderful and exceptional we are and clearly we're saving the world But I've noticed in that time that there are two things that we really tend to ignore as engineers Anything that was invented a long time ago where that that's a sliding scale Those of you are fairly young. This is probably like, you know, like five years ago seven years ago And then things were invented by non-engineers We we pretty much just remake everyone else's fields and so Designers like the this usability stuff is designer stuff. It's not like engineer stuff This was I googled a designer stereotype and this was like the nicest thing that I found And this guy is not one of us right like he he seems He's definitely not an engineer and he seems like he was probably invented a long time ago. And so and when you and when you read the book He's talking about You know, it's literally it's long enough ago that he's talking about like doing spreadsheets on like a green and black screen And he's talking about all these you know, like faucets and things and so I think we tend to dismiss that experience and To prefer the things that we kind of just come up with on the spot because we're engineers and you know We can we can invent stuff And I think we're missing out And this is my contention is that the Decades of work that they've done in usability has given them them us Has given them a vocabulary that they can use to describe these concepts This vocabulary is very rich and it helps us to think about these concepts There's a big power in having these words and having these things defined and I think that our Code is an interface We may feel like the the code itself is some like magical majestical thing But the the words that you write are really almost tangential to what the computer executes right the words that you write are there for you The computer has to translate them to do anything and so I think that these principles actually do apply And I want to take a look at them done ranting. It's all happy from here on out And so let's try it. I Want to talk about a couple of the principles in Don Ormer's book and I want to talk about how they can apply to code So first the Gulf of Execution In the book the design of everyday things he talks about the Gulf of Execution and the Gulf of Evaluation Gulf of Execution in in a nutshell is a way of describing what we do When we have an intention and we want to actually act on it and in short the part that's most interesting is Is there any action that corresponds to my intentions when you have a door you look for a handle, right? So think about this in a code perspective Let's say hypothetically that I am new to rails as some of us have been in the past And let's say that I have an active record model and let's say that I wish to remove it from a database All right, I don't know the action for this and so I'm gonna look Because I have done a couple ruby tutorials. I am very clever I am going to take a look at the methods and I'm gonna sort them I'm gonna see if there's an action that corresponds to what I want to do. It's less than successful. I Did put a red box on it if you if you can see that far And so obviously I you know have no idea what I want to do And so I get clever though because again I have taken the tutorial and so I am going to grep And so I will find the method I want but What do I grep? Dynormant's contention is that the model that is in my head is the one that I'm going to use to try to find an action And so in my head is somebody who has done the web before HD verb delete equal statement delete arrays delete delete delete delete Obviously I do delete and so I get the method. Yay, right? Awesome all good Yeah, fantastic. No problems Only except clearly that's that's not right for those of you who have done rails a little bit longer, you know the delete Despite being the thing that clearly I would find causes data inconsistency in my model fantastic destroy is the thing that I want and But destroy doesn't map really naturally to any convention. I'm aware of and so For those I can't see whether there are rails core committers in here that I'm offending There's a good reason why there's a destroying to delete and it's bullshit Because every new person as they come to the framework Get confused in the exact same way and we didn't have to name the thing delete, right? We could have we could have named it any number of things we could have named it destroy without callbacks But so by putting this thing in the way of course now I get tricked problems Gulf of evaluation Once I've taken an action I I Perceive feedback from the system and I want to see if I've succeeded the action did it work So in the in our code, this is actually is reasonably straightforward everything in Ruby has a return type, right? And so you have to give feedback And so if you're giving even some like minimal amount of thought to what kind of feedback you give this This should be pretty straightforward and and delete It's kind of does something reasonable, right? Like I don't think this is an Unreasonable return type for delete it didn't throw an error it didn't return falsi or nil or you know anything like that So it's probably reasonable It also happens to be virtually identical There is actually a difference between the two of them But it's almost identical to destroy and so In one sense we did give good feedback Interestingly like it succeeded in deleting and in another sense it failed to warn me entirely that I've corrupted my data model This is less than optimal Right It gets even worse when your code is not in an execution context Ah this if you do Return types if you think about other things like destroy all this is actually a useful return type I don't think that that would work for destroy or delete But it's useful to know this kind of thing in a in a non-code context And then have any of you done this before first of all, do you see why this is a problem? All of my new people when they learn they have this problem We declare private and then we start to declare static methods. This does not work There is no return or anything on that private modifier And so there's really no indication that you have done anything wrong the way that they typically catch This is either in code review or if they run like RuboCop It'll tell you that you've got useless private statements in here And so with the gulf of evaluation the question is how Can I provide feedback such that I? Can catch this kind of mistake? I Would tell you I don't have a great answer for this one. I you know, maybe you threw a warning I'm not really sure precisely how you fix this But we should be aware of these places where we we create a system that leads somebody down a path where They have no way to evaluate their success as to whether they've they've succeeded So now a natural mappings This one's cool. The the explanation for it is so cool. I'm not even gonna like use an analogy Stovetop right and we're gonna stovetop. It's got four dials on the bottom. They're laid out in a row and so if You want to turn on one of the dials you read it and you decide which one it is you turn on not a big deal, right? But if we do this instead The labels aren't even necessary anymore and is it a huge difference? No I have turned on my stovetop like 90% correctly since the beginning of time and it's the confusing one not this one But these things add up and if you think about that in a code context How much time and effort it takes to add up to to get these mappings right when they're a little bit wrong? And you knock the person out of flow when they have to go look it up when it does unexpected things it becomes Really evident how important getting these mappings right are So what does that look like in code because we don't have you know, there's no ovens. There's no dials So I think array and ruby is a really cool example If you didn't know how to sort an array and ruby you'd probably guess dot sort right if you didn't know how to get The first element you might guess dot first if you want to delete something which you know back to delete You kind of guess the delete and then it works It just kind of works the right way and I think that that's a really cool example of An API where it really doesn't pull you out to think about it because all these things are are mapped to the ideas in your head counter example I Screw this up every single time every Twice in a row it doesn't matter I screwed up every time because these two ideas have kind of like jumped on top of each other and the one that I want when I want to update my software is very clearly Unfortunately, not the update one. So this is it's a mess when Again, I'm not entirely sure what you do about this one But I think maybe we need to think about how we can define other words how we can take advantage of not overloading these meanings This is another really good one. This is the These are in the file class in Ruby in the standard library. These are all the path related methods There's two interesting things here one. This is a mess There's no there's no like mental mapping for the majority of this the difference between like path real path real dirt path Big mess as a counter example really interestingly if you've used eunuchs for a while the idea of relative path and absolute path very much our natural mappings and So absolute path can be natural for some people can be for some context isn't for others So all this stuff is very very situational Which makes it difficult to? design for everyone so Not sure what to do with that design for errors. I Don't know about you for me if I'm coding for say eight hours About five of them my software is broken software screwed up all the time all the time and so we need to design in such a way that We can recover from that and then we don't get pissed off by that This is my daughter Her name is Lane. She is 10. She's learning JavaScript And so maybe a month ago in the kitchen making dinner, but she's off on my computer programming I start to hear annoyed noises. You can tell when a kid starts to get frustrated like you know first she goes All right, and then a couple seconds later And so you know and she's kind of like building up this amount of anger and so I finally say what's wrong and then she says it doesn't work We're working on bug reports with her. It's you know, not a very clear report. I say I say, okay What does it say? It says undefined is not a function Right This sucks It it doesn't tell you where it is It's really like what does that even mean? It's in JavaScript that even better like it's like forget it. I'm just gonna stop executing It's like not only am I not gonna tell you anything. I'm gonna stop doing everything else I was doing you know take my toys and go home and especially in JavaScript We have this you know spooky nulls at a distance kind of thing I don't know what the name of this term is but you know We're like the thing that became null was was three methods ago But you never quite got around to throwing an error and so she has this issue where she's futzing around with the code where it says It's a line 17. It's online 17. No, it's not online 17. It's in some other place entirely We can do better than that undefined is not a function is is lazy It's easy to write that response But it's lazy and so the people the the ten-year-old child has an impossible time with it One more from Don Norman exploit the power of constraint. I love this one Basically, if it's the right thing to do make it very easy if it's the wrong thing to do make it very hard I saw somebody tweeting like literally 20 minutes ago that people just blame the library But I think that there's still a lot of space in this To support it so make it hard to do the wrong way. I am not a heathen I don't use my sequel anymore, but when I did this was the coolest flag in the world my sequel dash dash I am a dummy It means that you cannot run like delete from users Period you have to add a like where you know ID equals to it would refuse to do these things for you and I set this up as my default because Like many people I once fucked up the production database And so I thought that it was very important to not do that again on account of wanting to be employed and so This is a wonderful thing because once this is in place. It's very hard to do the wrong thing Ruby is this console in production development or test Yes Right and So If you leave a console open as I often do and you come back to it and you have many windows as most of you do You don't really know what this is And so when you start doing user last and you like hop back into this thing and you're doing debug statements This is how you delete production data Fantastic And you may be thinking to yourself like oh, no, I would never do that that would be dumb And I have to ask you have you ever programmed well really tired Have you ever programmed well really angry or even better? Have you ever programmed while really drunk? Yes This is the thing that happens and and it's just as easy as as you know falling off a lie I don't even know what the there's an idiom there. I don't remember. It's it's really easy to do It's terrible to do to your users So this quote yesterday, it's like a retweet of a retweet of a retreat you write code that drunk children would understand now What I learned is that Sandy Mets condones children drinking and I just want to I want to go on record that I don't support that That is illegal and immoral but we should be writing code that is that works when you are compromised and distracted and Everything's on fire and you have to remember that your user in this case the user of your code is probably always compromised in this way So I was thinking about these things This was this was a couple years ago and and like everyone else I incorporated some of this but I certainly still don't consider myself a usability expert, but I came up on This blog post by this lady Whitney Hess This blog post is called so you want to be a user experience designer and no I don't So it's a failed blog title, but There are a lot of cool principles in there. So whereas Don Norman is writing from the 1980s to me here. This is a lot more recent There are some really cool Articulable rules and again, I just want to walk through some of them and kind of illustrate how that can help us out So grouping related objects Objects that are close to each other Have an implied relationship And when I read this my very first thought was if any of you have read a ob-de-grim confident code Hands I'm gonna make you keep doing hands. Oh, we should do it by like applause. Let's do it by applause Who's red? That's great. It is a great book and at the very beginning. There's this like mind-blowing. It's like in the preface It's not even part of the book and he looks at this code This is actually from the talk of the same name that he did and this code It doesn't don't stress too much about reading it The idea is is that the code is doing a lot of different things and because they're interspersed You have to keep changing contexts and you have to keep going back and trying to understand what happened in the previous one And it's very difficult to understand as a result This is the same thing reorganized This was like mind-blowing. I don't know if your mind is not blown by this. This is a big deal for me By rearranging it in this way It's very easy to understand because the entire beginning is all about gathering input And so they are all next to each other. You are thinking about gathering input when you're reading this code There is none of it hiding at the bottom that forces you to backtrack The relationship of these objects is clear and it's being exploited in a way that is Really good for the user who has to read this code Be consistent. These are not in order. I'm gonna jump back and forth If we have gulp up case, what do you get? Big gulp. I thought I was gonna get two chuckles And you do big gulp.upcase. What do you get? You get big gulp You do gulp.upcase bang. You get big gulp What do you get when you do big gulp.upcase bang? somebody knows Clearly like it should definitely be the same thing No No, it's not This is ridiculous. Again, there is probably a really good reason for this. I don't care. It is bullshit People are using this code and this is super surprising and remember that when they use this code It doesn't look you can't inspect it for those title case. It's gonna come from the user Which means you have one of these bugs where you know one in ten thousand users ends up having an issue, right? You catch your your test no problem, right? No Because when you write a test about this sort of thing, you don't write a test that does nothing None of us think about writing a test that asserts that an uppercase word is still uppercase It feels like a waste of a test and so of course you have this test test passes No problem that inconsistency is is poisonous It's one from Rails production production dash E production Same thing There is probably a reason why it's stash E. I do not care because I get it wrong every time and The software should be working for me use emotion Coolest emoji I could find so this is an important one that was really obvious after I thought about it But wasn't really obvious up front We have a an emotional relationship with the software we use and I'm not just talking about when you use Mac or you know Whatever, I'm talking about when you integrate pieces of software when you write code you have an emotional relationship to that software I don't approve it I'm gonna say a word. I'm gonna put it up on the screen And I want you to make a noise that corresponds to your feelings about that software and so it's like a yay or a boo All right. It's an easy one rails where it rails cough Really good they're quiet over there. They're emotionless robots. It's all right. You can catch up So this is the best for me adequate record fantastic coffee script Great right so We totally have an emotional relationship of this stuff and and it's it's great because Even in Ruby this is something that we acknowledge because we have a language that was designed explicitly for developer happiness This is something you should keep in mind when you develop your code Is that when you work with code that is joyful when you you have this is this library that just colorizes the dots on your R spec tests The entire library Colorizes your dots. It's a fabulous test and you know what I feel really good every time I have fabulous tests and that makes a significant difference in my day Warmth and kindness makes software a pleasure to use this is important stuff and when you do that people will want to use Your library they will want to kill you less. It's an important thing Void jargon Another quiz it's very audience participation. I was assuming you'd be asleep by now By show of hands no snickering. Do you have CSRF's enabled on your app? Cool, who doesn't know Okay Same question. Do you use protect from forgery on your app? It's the same thing The people who built this feature were wise enough to realize that when you're implementing your app To say something like protect CSRF on Action would not work. This is not a an acronym that is known widely And it's not something that you want to try to retrieve or Google and so people will just not do it protect from forgery Fantastic, it's not jargoning. I know what it's doing. And so of course I try to apply it to everything It's an important distinction that the CSRF library would not be as successful without This lack of jargon Ajax counterpoint with Ajax I Think maybe it's okay to use jargon. I think that this is probably prolific enough that that's acceptable So it's very context-dependent Some things you can't expect them to know some things you can It's the last one signposts and cues Straightforward enough. Where'd you come from? Where you go? So when we look at this What can I do next with this object? If you think that the documentation is a sufficient way to tell me what to do with this object Fuck you It's lazy thinking When you think that you can design software poorly but point me towards a web page somewhere That's hopefully up to date on on how to use this thing. You're causing me those paper cuts You remember the the oven and the natural mapping right when I have to read it slows me down when you send me to the Docs, it slows me down This does not point me towards anything that I can do and so it's not okay This is an interesting one. It's I can kind of tell what the method is doing, but if I want to look it up I'm not gonna be able to look it up. I can't Google find by email and first name right and If I want to put a different parameter in there It's I have to start to think about what can I put it before can I put it afterward? Is there an aura? How does that work? The newer syntax for this Way better if I want to look up dot flying on active record It's actually relatively simple by being able to say email and last name. It's very easy for me to tell what this thing does One last example Aaron Patterson a couple months ago He was talking about our spec and I thought this was a really neat example If you have this code again, don't fret too much about reading it If you run a spec and it fails It tells you how to rerun the spec You can paste this command into your terminal again, and it'll run just the failed test. How cool is that? So it points you towards what you need to do next which is rerun your one test It's very easy to see where you came from very easy to see what you do next So what do you do if you how what do you get if you invest all the time to learn these things? So you get less suffering there's this wonderful quote in that blog post the world is filled with anguish Let's not add to it This speaks to me as somebody who's worked on production code bases I'm not sure she wasn't writing about us because this this Encapsulates my entire experience of developing and so we should be not contributing to that anguish and also in this one I'm not sure about it, but I'm thinking about it And it seems to make more and more sense and more I think about it I think that if you believe in self-documenting code and fairies I think that this is a mechanism for self-documenting code And I'm not contending that if you do this right that you don't have to write any documentation whatsoever what I'm contending is that Self-documenting code is not about code It is about the people who perceive it and So when we use these techniques People will understand our code the cognitive burden is lower And I think that this is what we mean when we're talking about self-documenting code Code that humans can understand And so as a last request, I'm just gonna say please go out the the blog post is literally like 2000 words long take a look at it think about what you do with your code if you maintain a library Think about how people perceive that library and what those stumbling blocks are All right design of everyday things amazing book recommended to everybody It's all I got