Ready for Readable Code? - John Papa

what a great conference isn't it it's awesome conference great keynote i love seeing how things are getting easier from the angular team so it's wonderful thank you so much steven and rob so i want you to all start off today with a little bit of a story from me i'm going to have you close your eyes which is a little bit scary at 9 00 a.m on the last day of a conference but bear with me imagine we're all back at work we had a great time this week but next week the real world starts we're back at work now and you know you're hanging out with your friends you're coding some new angular 6 application you're just loving what you're working with using some stack blitz and then a production outage happens uh oh man i should have taken an extra day off right stayed a little bit longer so you start going through the process you try to figure out what's the problem what's the error start doing your debugging so we dive in and we figure out after some time where the problem is and we see through the get history of our application that something was removed from github dear developer we found this line of code if you're reading this there may be an outage uh-oh we found our logs and they can crash the server when they're too full if you remove the code put it back now so you see something like this in there and we look at this and go well okay great we found a problem we can put the line of code back but why did this happen why did this happen in the first place could we prevented it could we have reduced the amount of time to get to this point in the first place these unfortunate events are our lives so my name is john papa and today i want to talk about readable code it's a concept that i'm very passionate about it's something that i think all of you will find that you do to the best of your abilities but sometimes when we know something really well we forget how important it is we forget to dot the eyes and cross the t's right so where do we spend our time how many of you here raise a hand think you spend more time writing code i don't see a lot of hands i don't see a lot of anything because there's a lot of bright lights so i'm going to assume nobody said that i'll tell you our little secret in the developer industry when you talk to your employers prospective employers and you ask your family what do you do for a living what do you say i write code do you really are we liars the ratio is vastly in the camp of reading our code just ask uncle bob there's been a lot of studies in this so what can we do i mean even think about code reviews we measure code reviews on the amount of time it takes to understand what's happening don't we this is what happens at work when burke holland writes code burke's a great guy so it's not about red code it's not about being clever crafty artful we always hear hey i wrote this really awesome thing it's a nested ternary function you're like get out reading code is about fast and effective communication have you ever had to read someone else's code have you ever wanted to chase them down has that ever been you you want to care about the developer behind you so think about it look at the developer behind you right now you're writing code you're out for a run you're having a good day imagine the developer behind you looks more like this readable code is the idea of making these things not happen so often all right so caringbuttercraft is a good thing right but caring about what happens after we deploy is really important we like to write code yeah yeah we like to read code too but after we deploy who's going to maintain that sometimes it's you sometimes it's the person next to you so what about the motivation for this i mean the productivity over time for a complete mess and this is what we get in a lot of our applications why do a lot of applications get rewritten because a lot of times people come into projects and can't figure out what's happening in the code base right now so hey we say we're developers we can write for angular 6 now right it's a great time it's a complete mess let's rewrite it and we're sitting at home like yeah let's go you know and you go tell your boss hey get good news i can't read any of the code let's rewrite it and they're like no don't think so so how do you make your code easier to read that's a really good question some of these things have been around for years and years and some of these i think you'll find you do in the subconscious so first start with some kind of a style guide the angular docs provide one for us uh we have several folks contribute to this and it's really nice because it gives us a lot of the common sense stuff like the one i'm pointing showing here is for naming conventions that's stuff that you do in any language anywhere it's not like these are angular specific things for the most part but they're important to have some kind of a guide one of the first things people say to me when they say hey john i love the original style guide you wrote i say thank you the next sentence is almost always this but i hated these three things i'm sorry so i made my own and i'm like don't hate on it that's great that's the whole idea of a guide make what you want for your company the important thing is you have something at your company your team so starting with those helps you avoid things like this writing a function to divide div x y with a value when somebody goes and reads this it's a lot easier if you can actually read the variable names and the functions and it doesn't take a whole lot more energy you think about this when you're writing your code not too bad what about apis for services in angular using ngrx maybe we do something like hero dispatchers get heroes make the code easier oh okay it's going to go get my heroes i'm going to open a snack bar and put a message and a title in there readable code makes a big difference now we all know the cookie rule right you drop a cookie you have five seconds to pick it up and eat it some of you five seconds is more like this one so what do we do in the coding world i have this rule i try to tell my developers on teams we have a five second rule in reading code doing code reviews if you can't understand the code in five seconds that's probably a smell that's probably an idea that you should refactor a little bit so here in five seconds can you figure this out one two three four five no you couldn't so instead what you could do is rewrite it with functions in the middle just makes a little bit easier abstract into functions is an easy way to do this and guess what all modern tools have it vs code you right click extract this into a function and you're good to go above the fold is something we hear in newspapers but for most of you that's a big piece of paper with news on it done i haven't seen those in years either so newspapers say above the fold is important stuff should go in coding we have this similar kind of concept the most important stuff should go first an angular we put our properties and our methods up top then we put all of our stuff sometimes organized alphabetically sometimes by events sometimes we break them out by decorators or not the point here is not so much how you do it and the fact that you have a consistent way of doing it to put the important information up top so you can read it especially as files get longer organizing our code is important sometimes we have code for doing like an upsert where you're doing updates and inserts in the same code this code is arguably not too hard to read but it could be easier why not just have an add speaker function and have an update speaker function and have something simpler that just calls those breaking things out into more functions constant iteration you want to look for other signs where you might want to refactor for readability in your code as well less than 20 lines this is a general guideline i have it's not hard and fast but if it's too big and some people say it can't be off screen some people can't say more than 10 lines it's really whatever your guidelines say in your company it helps you read through the code faster once you get beyond this mark though you start seeing those signs of maybe my code is doing more than one thing maybe it's doing more than seven things maybe it's time to refactor out just a little bit i worked at a company where people thought it was fun to misspell and this is actual code i'm not kidding this is going to be actual code i saw at a company and i had to literally pull this developer aside and go what are you doing and they were laughing the whole time they're like this is so funny let me share you're like who cares that misspellings right i'm han solo well writing code how many misspellings we possibly put in five lines of code i mean seriously abbreviations misspellings by the way those are customers not customers and my favorite one was here i went looking through the code to maintain it looking for any functions that did validation so silly me i searched for the word validate little did i know that validate was actually spelled wrong all my entire life these kind of things can actually hurt you in code so spelling can be a good thing stay in school kids maybe rewrite it something like this readable code people who maintain the code also lack the author's context have you ever seen someone's code and they you look at it and it's clear to them they're like why are you so dumb you can't figure this out it's because sometimes the person who wrote it had the curse of knowledge they knew something that you didn't some key piece of information that dictated how they wrote that code context is clarity for example if you saw this movie you know this was a key moment in the movie everybody in this here probably seeing some ward bell by the way make sure you make fun of ward for not seeing star wars you won't miss them so in this movie this is the moment where he reveals that he is luke's father and this is a really important turning point spoiler now imagine the first time you saw this movie ward you tuned in at this scene you'd be like yeah who cares there's some weird guy in a big black helmet telling me he's his dad and the guy's like crying about it get over it in code this is kind of important right so providing clarity through code first sometimes we look at comments as the way to go there but i'll tell you i think code is a better way while this comment works check if the hero can defeat the villains and tour heroes hey he's got more super powers but maybe she's got more energy or maybe the villain is in monster mode you know we have to check to see who can defeat who what happens if this logic changes and the comments don't because how often do you honestly update the comments when you change code i know i don't instead self-describing code write a function hero can defeat villain little things like this very easy to do refactoring abstracting always opt for self-describing code over comments to describe a what replacing magic strings arguably this isn't too hard to read we've got some nested strings in there but it might be easier if we pull those strings out into constants might even get some code reuse and then put those into our code make it more readable code comments must be readable and maintained they are technical debt how often do you look at code you see a comment and you're like i have no idea what that's referring to it's in the middle of nowhere someone else wrote it i it's probably from eons going by so when do you avoid comments this is what i recommend if you're explaining what the code does here's the beginning of the if here's the end of the if thank you i was kind of confused i thought the end if was the beginning but now i know explaining for example at the beginning of the conversation we talked about we're imagining the production outage what if it just said hey leave this code here great why why do i leave it there we go on further to explain outdated and incorrect easy to understand we don't want old comments they're actually worse than having no comments because it misleads you down the wrong way or you shoulda coulda woulda used some kind of a welding function or variable okay picking on burke i think he tweaked it tweeted this morning i loved this little quote code never lies right but sometimes developer i mean sometimes comments do sometimes comments will lie so when do you use them if it's explaining why something's there some kind of unexpended consequence too or you're doing some kind of api docs like with js docs that will clearly help you out with readable code so there's times to use comments for example regex who here can actually read or regex that's more than three characters long i mean seriously what do they say you've got a problem solve it with a regex now you have two problems great place for a comment in fact i would do a function with a writes name like validate email and put a comment then they're saying what the heck all those letters do so and comments can be helpful yes not saying don't comment at all i'm just saying think about where you do comment and how it can be helpful and who's going to update that okay so at this point you're probably feeling a little bit sad like i do a lot of those things i do them too nobody's code is perfect when they first write it but here's the thing you write your code it's dirty and then you show it to somebody and you clean it up or you show it to yourself and you clean it up and you iterate over it you read your own code put your own code down for a day and go back how often do you really understand what it did the day before if you don't that's a great sign that maybe you need to refactor to make it more readable and try some of these tips so at the end of our story dear developers this is to all of you writing code will make your app easier to maintain it'll make it live longer it'll make your bosses happier it'll help you update your apps it'll save you and the next developer that might be you might be somebody next to you as well so here's some tips just to leave you some thoughts the five second rule it's really easy we all know what it is by the cookie dropping on the floor we can do that with our code too can you read it quickly efficiently if not take another look one thing per file that's another guideline one thing per function small functions in general if you see nested ifs in a function probably a case to refactor if you see a lot of conditional logic i generally look for branches in code i don't want to have more than two inside of a function generally well thought out naming probably the hardest thing to do in coding right but good names are worth the time that we invest in those crafting your own style guide choosing comments wisely and using tools like prettier stop fighting over spaces and 80 line characters and where you should put the curly brace use tools like prettier set up a tool a prettier rc file in your project and just call it a day those things are much easier to handle and share it with your team and if you want any links to some of these resources the angular style guide is right up here brings you to the angular site vs code does a lot of this stuff for you angular essentials has a lot of this readable code stuff in it out of the box i've got some code snippets in there that a lot of people use a couple million downloads on it so thank you very much for for using those helps you put things formatted right according to the cli and the style guide also has prettier baked in and my favorite extension the world which is called setting sync so you can set up your environment with your settings and extensions and share it with your entire team by checking into github and finally since i always get asked hey what font was that you can also check out my fonts in the theme called winter is coming i use those also in the deck so thank you very much for coming and i hope you all write more readable code

Channel: ng-conf

Views: 63,316

Rating: 4.9562311 out of 5

Keywords:

Id: 56mETnrByBM

Length: 16min 50sec (1010 seconds)

Published: Fri Apr 20 2018