How To Write Cleaner Code - A Practical Example

Key Takeaways

[Music] hello everybody and welcome to another youtube video so in today's video i'm going to be showing you how to write cleaner code now the way i'll be doing that is by going through a script that i wrote about three or four years ago just pointing out some of the flaws in it and showing you how we can make some minor refactors and changes that just make this code much cleaner easier to read and just better in general now clean code is a subjective topic some people will say one script is better than the other or this way of doing things is better than the other way but a lot of stuff that i'm going to cover here is not really controversial this is just stuff that generally will make your code cleaner and so take everything i say with a grain of salt but generally the stuff i'm going to show you here is a best practice and at least in python what you should be doing so before i actually get into this i'll just quickly mention that all of the code here again is from a tutorial that i made about three or four years ago so this tutorial was called projectile motion in python using pi game i'll put the video up on the screen it's still on my channel so if you want to actually you know figure out what all of this code is because i'm not really going to be explaining what all of it does we're just going to be refactoring it then you want to go back to that video watch that video it's it's pretty old but i'll show you what the kind of output of this code is so it's actually a little game that allows you to simulate projectile motion so obviously you have your cursor and you can see that this line is kind of you know sorry the line is tracking the cursor the further you go out the more power and then you can pick the angle you want to shoot the ball out and well it's just meant to kind of you know be a little bit of a physics simulator sorry i didn't implement any bouncing in this but i have another version not really of a tutorial but of a game that i showcase where this uh this ball actually does bounce on the screen anyways enough of that just wanted to show you what the output was now let's actually go through and refactor this i'll start by just a high level overview of all of the code it's not too long and then we'll see what's kind of not clean and what we can change so this is a python game using pygame so you're going to see a lot of stuff related to pygame we're not really going to be changing any of that because that's just the module itself what we will be changing however is stuff like the ball class right or like the different functions that we have so first of all we can see that i've defined the width and the height of the screen i've set up a window i've set up the name of the window and then i've created a ball class now in this ball class i have a few attributes the x y radius and color of this ball right the properties of it i have this draw method this method allows me to actually draw the ball onto the screen and then i have a static method that allows me to calculate the path of the ball based on a power angle start x start y and amount of time okay so that's what that's doing this is kind of running a lot of the physics here it's calculating where the ball should be moving to at a certain point in time okay we have this redraw window function this will redraw the window every frame so you actually see the ball moving we have find angle this finds the angle between the mouse cursor and the ball yeah so where your mouse is relative to the ball it's kind of that line it's finding the angle of that line we then create the golf ball we have a few variables here that we're using we have our main while loop we have some clock and then we have if we are shooting the ball do all of this stuff okay we defined the line so the line goes between the golf ball and the cursor and then we are drawing the line constantly and then we have an event loop this event loop is just handling okay what actually happens when we press the mouse button down or when we quit the window okay so high level overview there and as i've scrolled through this you guys have probably already realized a few things that aren't really that clean and that could be fixed now the first huge thing that screams to me when i read this code here is why are you not using snake case now i'm going to kind of be speaking in third person here because i can't remember what i was thinking when i wrote this code three or four years ago but i look at this and i say okay the python convention is snake case and all of the module stuff like set mode set underscore caption it's all using snake case but everything else is using camel case now it would be okay if everything was just in camel case that's still not preferred but at least that's consistent but we're mixing and matching here and since we're using a module that has snake case and then we have camel case for the rest of it that's just not good that's not very clean you want to be consistent even if you make the wrong choice at least consistently make the wrong choice that everything's the same so the first thing i want to do here is just go and change everything from what is this camel case to snake case because in python we don't use camelcase also stuff like this w screen h screen these aren't really the best variable names yeah i can figure out this is width and height but i probably want to change this to just say width and height and also these are constants let me zoom in on this a little bit these values i don't think are changing anywhere in the program in fact no they're not and since they're constants the convention in python is to make them capital so what i'm going to start by doing now is just changing these here to be all capital so i'm going to say width for the first one oops that's not what i want to do i want to find and replace so we'll replace that with width okay replace all and then we're going to go here and we're going to replace this within all capitals height okay replace all nice now the next thing that i'm realizing even if i'm just on line seven here is i don't have a space after the comment now this is not a huge deal again these are very nitpicky things but i like to have spaces after all of my commas that's just usually best practice okay so now up here at least this is fine imports are at the top of the program i can live with that let's move down okay next i see this class now the first thing that really bugs me about this class is inherits from object now i know why i did this because back when i was yeah three or four years ago i guess whatever age it was at that point in time i just always would inherit from object because in python 3 all classes do inherit from object and so like doing this doesn't make a difference but the point is we don't need to do this so there's no reason to inherit the class from object or have the super class b object so we can just remove that the next thing that's bugging me here is this class name does not have a capital at the start so i'm going to change this find and replace here to have a capital so like that this is because the convention in python is to have pascal case for your classes so you want to have a capital on the first word capital on the rest of the compound words inside of it so there we go now this says ball that's better looking nice okay same thing here i don't have any spaces after my commas so i'm just going to add those in because again that's just something i like this is fine right here for the init and the draw method looks fine as well but the next thing i see and again these are all really nitpicky things but just small things you can do that just make your code higher quality is that i have a different amount of spaces between my methods here so notice i have this first method this second method and this third method and there's two spaces here and one space here vertical space right so what i'm going to do is just keep this consistent and the python convention is to have one space in between the methods and so i'm going to make that one space and just move this method up nice now i'm looking inside of this method there's not really much we can do to clean up here i mean i can add in my spaces which i like and again notice how it wasn't consistent right i didn't have spaces here but then i had spaces here so at least be consistent in what choice you make and then same thing here i like to have spaces in between any operation so i can more clearly see what the operator actually is so we'll just add the space between the minus all right next i'm coming here to ball path all right now immediately i'm a little bit confused because i start by defining angle equal to ink now ang is my parameter angle is here it doesn't look like i'm changing angle at all and so this doesn't really make much sense for me to do what i'm going to do is just change the parameter name to angle rather than renaming it inside of here okay so we'll see if we have to change anything anywhere else because of that but that's fine um yeah okay so now the next thing that i'm seeing is again this method name is not snake case so i want to change this to snake case not camelcase so let's find and replace and let's replace this with ball underscore path okay uh replace all nice okay now we have that now same thing here for my bell x and my bell y i want to change these both to be uh snake case so let's replace vel x with vel underscore x obviously we got to spell that correctly and vel x is fine uh that's descriptive enough but normally i would probably name that velocity x velocity y but that's fine we can leave it the way it is okay so let's replace and there we go okay that is better now same thing here with this x and dist y and even notice if i go back here right i had vel y but i didn't have a capital y and now i have dist x and i have a capital x and i have a capital y and so i wasn't being consistent and you want to be consistent again even if you make the wrong choice just be consistent with making the wrong choice okay so let's go here and let's change this to be dist underscore x so replace all and then let's go here and let's change this to be dist underscore y okay and again that stands for distance it might be useful to actually add the distance x and distance y but i think that's descriptive enough most people can probably figure out what that is that's the whole point you want other people to be able to read it okay now i see start x and i see star y same thing here we need to change these so that they are camelcase so start underscore x start underscore y and by the way i should have mentioned this before but feel free to go through this and find all of these errors yourself i'm just kind of walking through it as i would if i was going to refactor something and clean it up trying not to cut or anything but i understand it might be a little bit boring okay so next thing i'm seeing here is that this spacing is fine i did my velocity i do my distances i figure out my new x and my new y now the new x and the new y need to be changed as well i can just manually change that it'll probably be faster and then what i'm doing after this is i'm returning new x and new y in a tuple now the thing is in python i don't need to do that when i return multiple values they're automatically going to be packed together in a tuple and so i'm going to remove those brackets because even though they don't really cause any harm being there they're unnecessary and well you shouldn't really add unnecessary stuff to your code that just has you know the potential to make it more confusing now in this case you could say all right well maybe this adds some clarity because you're defining that it's a tuple but anyone that works in python and who would be reading this would already know that so that's fine okay so now the top part of our program is looking better i'm happier with that now and we still have more name changes to make right redraw window need to change this so that it is going to be snake case so let's go redraw underscore window replace all nice okay now we have a few other variable names i'm just going to keep changing them i think you guys get the idea now golf ball needs to be changed to golf underscore ball it's going to be a lot of a snake case we need to change or sorry a lot of camel case we need to change to snake case all right so now i'm going inside of here and i actually called this gold ball so let's just rename this to golf ball my bad okay and now let's see what else we could potentially change so we have win.fill 64 64 64. okay pygame.draw.line win color line okay i'm going to fix the spacing here with the commas same thing here but what i want to point out here is that we don't know what 646464 is right i have no idea what this is i'm saying fill the window in with this i know this is a color just because i work in pi game before but i don't know what color this is and so really what i should do here is i should store this in a variable and define what color it is so that i actually know what color i'm drawing on the screen so i'm going to go to the top of my program here and i actually don't know what this is but i think it's a gray i'm going to put gray in all capitals notice because this is a constant is equal to this okay and now i'm going to swap this out here with gray so this way when i'm reading this program the feature i know okay i'm drawing right onto the screen that's where i'm drawing gray now same thing here this color 0 0 0 this is black now what i'm going to do is i'm just going to put the variable name black here it's going to be a constant as well i'm going to define black up here just to make it easier to read okay so just small things but again makes a big difference okay let's continue here line zero and line one is fine all of this looks okay and now we're on to find angle all right so we need to change the name of this one again so let's go find underscore angle oops not in capitals find underscore angle okay replace alt and now let's look inside of here okay so the first thing i see that kind of bugs me is well pause i mean we could make this position but pause i think is fine but s x and s y i don't know what s x and s y means now i understand i'm getting the x and the y of the golf ball but i don't know why i have to have an s before i don't know if that means something specific and so i'm just going to go ahead and assume that it's actually fine if rather than having sx i just have x because i'm not using the variable x so let's just do that replace all oops what did that do oh sorry i need to do this okay sx replace that with x replace all and then same thing for y okay so here this was just a little bit confusing i don't know why i have sx and sy and again they're using camel case which is wrong so let's just change that to x and y and i think that's fine okay next thing here i'm using a try and accept now i guess this is fine i don't know exactly why i needed to do this try and accept but really you want to avoid using a try and accept when you're not actually accepting an exception in this case i'm not you know accepting a specific exception i just have a general accept and i'm saying okay if something goes wrong in this line i'll do this again that's fine you can do that there's not a huge problem with that but it's just not best practice really what i should do is kind of handle this error manually and say okay if whatever is going to cause this to error out occurs just don't do this do this instead so replace the try and accept with an if and an else statement that would be better unfortunately i don't know why this is an error my trigonometry is not primed i'm sure if i have like a zero or a negative or something maybe this fails but for now i'm just going to kind of leave that as is and note that that should probably be an if statement not to try and accept okay so now i come here and i say if pause one and pause zero if pause one less y pause zero okay so all of this looks fine i'm not really going to mess with this too much because i don't remember exactly what all this is doing but one thing that i will note is that i have pause one and pause zero now that is getting the x and the y coordinate of my position so really what i would prefer to do is to make a variable called mousex that is equal to pause 0 and then make a variable called mouse y which is equal to pause one in this way rather than me just having pause zero and not knowing if this is the ball position or if this is the uh what do you call it the actual position of the mouse i have this variable and that's easier to read so what i would do now is swap out all of pause zeros with mousex and with mouse y so let's just go ahead and do that we're gonna swap this with mouse underscore x okay replace all we'll have to why that not work pause zero mousex okay so i don't know why that wasn't working i think i had one of the modes wrong and it goes in like a regex expression or something uh but let's just replace all of those i hope that didn't change anything down here although it might have okay and then let's do the thing same thing here so we'll do pause one replace that with mouse y and then we'll have to change these back so these are gonna be pause zero and pause one okay nice so that's all right for now the next thing i'm realizing though is that i'm using golf ball but i'm not passing golf ball into this function right golf ball is defined down here i'm not passing that as a parameter i'm using this as a global variable that is bad don't do that so what i'm going to do now is i'm going to change this so golf ball is now going to be a parameter because it should be a parameter i shouldn't be able to just reference it out of nowhere and same thing here with line right this shouldn't be a global variable i'm going to put that here and i'm just going to go and look if anywhere else i have this being a global variable i don't think so but that's going to require me make some changes later in the program so same thing here i'm referencing golf ball but it wasn't passed in as a parameter and so anytime golf ball this variable is defined anywhere outside of this function that's what i'm going to be referencing and that is not good i don't want that so i'm going to change this so it's no longer a global variable okay so that's good for now now i see golf balls defined here that's all right and then i see i have my variables now one thing i would do is i would just add a space here just to kind of separate the fact that okay i got all my variables in fact this guy can be a part of this kind of stack of variables here i'll just make sure that my vertical spacing is consistent so after this function i should have one vertical space because all of my functions are separated by one vertical space and you'll note here that the class has two vertical spaces after it again that's kind of a python convention okay anyways now we're here into our wallet so i'm not going to go through a ton of this stuff because a lot of it if you don't know what it means it's going to be pretty hard to uh to actually determine but the first thing i'll say here is i have golf ball i'm setting the color to white but again this isn't in a variable and so if i don't know my rgb i'm not going to know that's white so i'm going to go up here i'm going to say that white is equal to and then 255 2v5285 and notice i've kind of put all of my colors beside each other i put my width and my height beside each other and this way it's just much easier for me to figure out what is the find where and i might even maybe add a comment here and just say you know colors and maybe screen size something like that this is pretty obvious i don't need to add this comment but maybe you do something like that okay now i also just realized that i am using win i believe if i go to redraw window as a global variable here and so i'm going to take in win as well i'll take in window uh just to make sure that this is not global and actually no we'll just leave it win okay nice okay so now we're inside of the wall so i'm just gonna start reading through some of this uh most of it looks good so far all right so most of this looks good however i see this p o right and this is just a really undescriptive variable name i don't know what this means even adding like an s to it right this would be a lot better i know that this is position but po is kind of meaningless to me and even now reading at this i don't know exactly what this is i think this must be the new ball position but i'm not sure and so i'm going to change change this is a new ball underscore pause i'm going to assume that's what it is say new underscore ball underscore pause okay and then new underscore ball underscore pause nice okay now while i'm at this i just remembered something let's go back to this function here and notice how i said mouse x equals pause zero and mouse y equals pause one there's actually a way to do this in one line now you can make an argument for which is better which is worse but i'm just going to show you the way that you would do this in one line because it's more pythonic so if i go to mouse zero there or sorry mouse y there and then pause zero plus one so this is kind of the replacement of those two lines there i'm gonna leave it like this because i think this makes sense because these two variables are kind of grouped together in a sense okay but this will automatically sorry it needs to be like this actually uh this will decompose the position and then put it into mouse x and mouse y so the x obviously here the y obviously here now the other way i had it like this this works as well but that kind of defeats the purpose this oops let's go back here is called tuple decomposition and this is just a better you know cleaner way to do it okay so let's continue time power angle shoot okay that all looks good this looks good but now i have my line okay so this is fine i can define the line here but i think it would be better if i define the line at the top of my while loop now i understand why i'm doing it actually let's see here i think the reason i'm doing it after is because i'm calculating the line based on the new golf ball position so maybe that needs to be there i won't question the logic for now i'll leave it there but typically i would prefer to define that at the top of the while loop just to make it easier to see okay and then i'm redrawing the window and then i have my event loop okay so this is fine the only thing that i'm noticing here is this if statement so it says if not shoot and then in another indentation level i have all of this stuff i'm going to show you a little trick here to avoid having all of these indentation levels in python when you have a condition like if not something what you can actually do is reverse the condition and then simply bypass the rest of the for loop and put everything else below the condition so what i'm going to do here is say rather than not if not shoot i'm going to say if shoot continue so the condition i wanted to check was if i'm not shooting i was saying if i'm not shooting i want to do all of this stuff so rather than me checking if i'm not shooting and then doing all of this inside of here i'm going to check if i am shooting and if i am shooting i'm going to continue which means i'm going to skip all of this stuff so only if i'm not shooting will i end up actually hitting this and this is just a cleaner way and this is showing you kind of the break condition of the for loop or the continue condition of the for loop rather than the condition for when this should occur so this should always occur unless this happens so again you can make arguments for which is better but i prefer to have less indentation levels and so i usually do it like this because it's easier to read now here i'm just going to fix a few small things notice i have pause is equal to this okay that's fine now i have line one one line two two okay i'm just going to space these things out because again i like to have spaces between my operators so i can see what's going on here okay let's space space space that and that is better okay see i find this way easier to read than what i had before and then everything else here looks good so let's just do a quick spot check through here see if there's anything else that i could change and maybe clean this up but i think for now that that is all good again i don't really want to get into changing the logic i'm sure i could mess around with some of the logic and make this shorter code maybe easier to understand code but i just wanted to show you a few small and very easy things that you can do in pretty much any program to just make it look cleaner right add these constant variables always define your constants at the top of the program makes it really easy to go and change something right for example let's say i was using some color a bunch of times in my program i could keep writing the same color using the rgb tuple or i could just define a variable that holds that color and then use that variable everywhere that way later in my program all i have to do is change that variable to change the entire look of the program right stuff like that is just really good practice i'd recommend you just get in the habit of doing that even in short programs because the way you practice is the way you're actually going to write you know industry code or code that you submit to people all right so with that said i think i'm going to end the video here i do apologize if this was a little bit boring but i just wanted to walk through show you my thought process when it comes to refactoring and cleaning up code and hopefully you guys got something from this and just saw how you can make your code a little bit more readable and just make it a bit cleaner one of the big ones and it only showed up once here but one of the big things is this the indentation levels if you can think of it this way if you can negate the condition that you're checking and then simply skip the rest of the block if that condition is true then that's going to save you or just make your code look a lot cleaner because you're going to have you're going to be able to avoid all these indentation levels right and something simple to show you here is a lot of times people will do these like very nested if statements they'll say if this and then they'll say you know if this if this if this and they'll have like four levels of indentation and then inside of here it's like okay do this right so it's saying okay check all of these four things and then if all those four things are true do this now of course you could combine these into an and and put those in one if statement but maybe there's a reason why you have it this way but what you could do here is you could change this and make this flat by simply changing it to be like this you could say if not this if not this if not this if not this and then do this and then what you would do here is you would just say continue or break right depending on what you're doing you would say continue or break to get out of the for loop or to continue with the next iteration and then you can do what you want to do so of course there's exceptions to this it depends on the situation that you're in but always think of it like this and ask yourself can i make this a flat indentation can i do four separate if statements or do i have to nest them in with each other because it's really good to avoid having a ton of nested statements it just makes the code really complicated and you want to have as many flat kind of levels as possible all right so with that said i think i'm going to end the video here i hope you guys enjoyed if you did make sure to leave a like subscribe to the channel and i will see you in another one