Readability Counts

Video in TIB AV-Portal: Readability Counts

Formal Metadata

Readability Counts
Title of Series
Part Number
Number of Parts
CC Attribution - ShareAlike 3.0 Unported:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this license.
Release Date

Content Metadata

Subject Area
Most code is read many more times than it is written. Constructing readable code is important, but that doesn't mean it's easy. If you've ever found unreadable PEP8-compliant code and wondered how to fix it, this talk is for you. Long-lived code must be maintainable and readability is a prerequisite of maintainability. It's easier to identify unreadable code than it is to create readable code. Let's talk about how to shape tricky code into something more readable and more maintainable. During this talk we'll discuss: whitespace self-documenting code modularity expectation management We'll conclude this talk with a checklist of questions you can use to make your own code more readable.
Web page Code Software developer Multiplication sign Control flow Line (geometry) Software maintenance Measurement Computer programming Neuroinformatik Software bug Mathematics Computer animation Order (biology) Data structure Whiteboard
Axiom of choice Context awareness Length Code State of matter Parameter (computer programming) Function (mathematics) Disk read-and-write head Mereology Heegaard splitting Programmer (hardware) Mathematics Strategy game Flag Endliche Modelltheorie Descriptive statistics God Vulnerability (computing) Scripting language Touchscreen Closed set Electronic mailing list Maxima and minima Bit Variable (mathematics) Data mining Type theory Arithmetic mean Angle Website Text editor Spacetime Functional (mathematics) Divisor Electronic program guide Control flow Field (computer science) Revision control Programmschleife Authorization Data structure Punched card Mathematical optimization Form (programming) Condition number Multiplication Consistency Projective plane Expression Line (geometry) Limit (category theory) Subject indexing Word Film editing Computer animation Logic Personal digital assistant Statement (computer science) Tuple Library (computing)
Logical constant Complex (psychology) Context awareness Code Multiplication sign Decision theory Direction (geometry) Sheaf (mathematics) Shape (magazine) Mereology Computer programming Optical disc drive Oval Videoconferencing Endliche Modelltheorie Descriptive statistics Exception handling Social class Curve Algorithm Email Block (periodic table) Closed set Reflection (mathematics) Electronic mailing list Bit Variable (mathematics) Connected space Data management Process (computing) Summierbarkeit Reading (process) Web page Point (geometry) Slide rule Functional (mathematics) Server (computing) Variety (linguistics) Electronic program guide Checklist Revision control Latent heat Programmschleife String (computer science) Code refactoring Hydraulic jump Task (computing) Condition number Information Inheritance (object-oriented programming) Cellular automaton Projective plane Database Line (geometry) System call Word Database normalization Loop (music) Computer animation Statement (computer science) Object (grammar) Abstraction Library (computing)
Histogram Open source Poisson-Klammer Connectivity (graph theory) Multiplication sign Projective plane Electronic program guide Electronic mailing list Rule of inference 2 (number) Goodness of fit Strategy game Statement (computer science) Square number Reduction of order Endliche Modelltheorie
thought of it and the 2nd time in
the name of a few the the new but
they're all the so what summary ability so before we talk about readability let's just can make sure there were all on the same page so textbook definition readability is really just a measure of how easily we can read or approach so I'm assuming you're all here because you care about readability but why do we actually care about readability what makes actually important I so every time you fix a bug change some functionality or add a new feature to your code you probably need to read some code so you probably read tell more often than you write it also you do sometimes be the change can code doesn't always stagnate immediately after you write it the in order to change something you need to read it so readability is really a prerequisite for maintainability you can have maintainable code of readable the lastly did not all teams are a moral values sometimes the the higher developers and those developers will need to be on board and you the lot easier time where people when they can read you care so before we get started at um was make it clear we're not talking about were not going to talk about how easy is to write code were not going to talk about how easy it is for the computer to read your code and run your code we're only talking about how easy it is for humans to read your column so we'll talk about the structure you code which pretty much boils down to where you put your line breaks I will also talk about the naming of unnamed things and also naming things more descriptively and finally will reconsider some of the programming idioms that we use every day I will be looking a lot of small code examples so if you can't keep up don't worry I'm between out the code afterwards there's a lot going on it all right so
let's talk about the structure of our in the modern age line length this is not a technical limitation more screens are really Lang Lang is not a punch cards it's about how readable your code is long lines or not easy to read the the when lenders live slydell because when it comes to readability indentation is quite the same as code so instead of focusing on that line length I propose that we focus on text with this is basically line like to read more the indentation now I'm going to average text with is I prefer Canada 60 character maximum but really most importantly we should focus on making our coder readable when it comes to text with and not worry about some arbitrary 1 short lines are not ah angle readability is a angle pilots at
about line breaks the so this code has a text with under 60 characters as you read this code you probably trying to figure out what it does you're not going to figure out what it doesn't you figured out what the structure of this code actually years will eventually notice at that 1st statement there has a generator expression with 2 loops and then that 2nd statement has a generator expression with 1 little and condition at the this kind of hard to read because the line breaks were answered completely arbitrarily the author simply wraps the lines whenever they got near some maximum text with the line like the other was evaluating text with were line length is the most important thing that completely forgot about readability this cut more readable this is the same code as before but the line breaks have been moved around the split the code the logical parts so these line breaks were not inserted arbitrarily in all these were inserted with the express goal of readability models that take a look at another example the let's say you were reading a jingle model and that 1 of your model fields has a whole bunch of arguments passed into it so we're passing a lot of arguments into this foreign key field here and its feeling a little and we have the this is a good way to wrap our code over multiple lines the but this way this is better or it is worse the but this 1 as compare what anything change if we were using exclusively keyword arguments here that affect the choice at all so personally I usually prefer that last strategy for wrapping my lines especially with all keyword arguments I almost always before the last 1 the 1st was a little difficult to read and that 2nd 1 that can become problematic you really long lines like you here aaai so let's take a look at that last strategy will more closely would it be better to leave off some the closing parenthesis or editor to put that closing princess on its online again a lot of God's here but what if we had a trailing comma was the improvement or is is worse better OK but it's a personally I I also prefer this last this last 1 here now I am certain that there some of you in this room were not nodding your head to disagree with this a preference of mine that factors OK the fact that we disagree it means that we need to document the way that we're wrapping our function calls in our style guide for every project we make we do have a style guide for every project you may right and I missed out it doesn't just mentioned had 8 and the dramatically drinks water here if you think about this the the the alright so consistency lies at the heart of readable yeah need to make sure that you are defining a diastolic I was really explicit mentions in every single doing a project in my the poets use a maximum wire length around their lines no output space that the line reads of purpose in poetry inserting aligned rig as an art form encode inserting a line break as an art form so as programmers we should wrap our lines with great care and remember all your project should have a style guide that goes well beyond the your code some convention should be explicitly document are that site about naming things the concept is important it needs a name names give you something to communicate about unfortunately many things is hard naming a thing requires that you describe it in describing a thing isn't always easy not only that once you describe it then we need to shorten the description to a name and that's not always easy the if you can't think of a good short name a long and descriptive 1 that's a lot better than a Subpart name that's really sure you can always shortening tomorrow it's hard to make an animal that long so worry about accuracy not the length of your names OK let's it take a look at some code with some were variable names I bet that you do not know what s c stands for this new I guess what that could not stand for South Carolina so you might know if you have more context which stands for state capitals don't use to other variable names in Python code user-script things not speaking of descriptive names what the CIA variable here represents the index OK is it a 2 tuple maybe something else is is I 0 capital-driven states or something else entirely so when you see an index access there should be a red flag index accesses can usually be replaced by variables we use a tuple unpacking so you can probably tell that s and c the state and capital or maybe you could guess that avoided using arbitrary indexes in occur whenever possible use tuple unpacking instead the so often a lot more explicit to have been the variables but it is to have the next year now you probably did guest SNC mean state capital for or maybe you know because I told you but there's no reason not to use real words here instead this makes the cut a lot easier to read and it was in that types name every variable with care optimize from active maximum accuracy and optimize for maximum weakness make sure you describing everything is going can OK let's take a look at an example code that can use some more variable names the this could returns a list of all anagrams of words that are in the candidates list not bad code but it's also not the most descriptive code the if statement particular is pretty loaded the library on there what if we abstracted out that logic into its own functions so with this is an anagram function here and I think it's a lot more obvious that we're checking whether 2 words are in fact anagrams we've broken down the problem and describe the process that we're using and left out the details the details are inside that function similar to that function so this is pretty much exactly what we had incited is there for you can use a little work of firstly word 1 upper word to not upper those both appeared twice we met some code duplication there let's fix that OK that's a lot better I certainly find conditional on that last line you read but I think they're still more room for improvement so 1 strategy that we employ here it is to read code allowed so I had to read my code allowed to see a descriptive is you works sorting our words checking whether sorted versions are equal and in checking whether the unsorted versions or ah sorry at checking whether the the words are not in fact the same word now that description took me a little bit to read because it's not the easiest thing to figure out that the script is a very helpful it's not very much like how we describe listening the we had some comments to describe this in actual english we can see that were actually checking whether the words have the same letters and whether they're not the same words now this curse for model but strangely but it is more descriptive we've added comments to describe what's actually going on whenever you add comments style that might be hint that you actually another variable name or a better way In this case we need some more variable lands so here we've turned those conditional statements
into 2 new variables that describe what they actually do are different letters and have same words but describes exactly what we're doing that last line literally says return have same letters and are different words we've broken down as problems make it more clear and more readable because of conveying the intent of our algorithm not just the details OK so we end up adding 4 extra lines that code but we broke down our process have been doing so it's a little bit more understandable at 1st glance you may think this example is silly I mean what we started with wasn't really that complex but this process was a worthwhile mental exercise regardless even uniform born occurring this code afterwards the the exercise of refactor your code to be more self-documenting is almost always a worthwhile endeavor it helps to reframe the way you actually think about OK let's take a look any complex jingle model method on a go through this 1 a little too quickly and there's a lot of code here I don't want to read this cone and like you to unfocused arise and focus on just the shape of the curve there which do it OK so the 1st thing you'll notice is that this code is broken up into 3 sections this 3 sections because there are 3 logical parts to this code if we had a very or if we had some comments to each of those sections we can better see what's actually going on now remember I said comments or it may be a step in the direction of making variables don't exist for making burbles with their names or missing variables here we couldn't name these sections by making methods for them so even when you see the code here you're tempted to read the common because the comments was actually saying what's going on now the 2nd step make methods for these if we split the sum to helper functions those names actually describe what the code is doing a left in the docstrings strings because I know there's no reason not to be not documentation like mentation is not quite the same as comments so always to to document things if we call those methods in original function this now describe the actual process is almost like English here if we want to see what each of these is doing jump into that function we don't have to be um distracted by the fact that it's doing some really detailed stuff on OK so brief recap reader code allowed to ensure that you're describing the intent of your algorithm in detail remember that comments a great for describing things but sometimes a common is just the 1st step toward a better variable names for a variable name that did exist before also make sure you're getting a name to everything the and in general described for descriptive and self-documenting OK so the sections a little long I may end up skipping over 1 or 2 of these all subsections here but basically let's talk about the code constant so we actually use and make sure that are code Construx or as specific as they should be when given the opportunity I prefer use of more special-purpose tool in a more general-purpose tool if it makes sense specific problems call for a specific solution so let's take a look at exception handling your opening a database connection reading from it and closing the connection we to make sure that we're closing the connection at every time that we exodus code even if an exception occurs so we have this try finally block here now whenever you see it any code that has come to clean up steps think about whether or not you can use a context manager it's not that hard to actually write your own context managers you just need a thunder and under eggs method but we do understand for double underscore the 1 who is not familiar that nomenclature let's look at how this context manager is actually used OK so this is a little bit more clear than what we had before in sense that were not distracted by the fact we have to close the or connections when we're done with every time the code does that work for us now we just implement our own context manager but the standard library already had 1 we could use in context with called closing not always have to implement your own context managers but you can if you want to and it's not that hard so when you have a clean that the context manager OK let's set up for this this code loops over something Intel at even odds were out in this connection is a little bit of something more than specifically the purpose of this code is to loop over something checking condition and create a new list for every item that passes that conditions so we using a list upon an if statement FOR loop to accomplish this task there's a better way to write this code 0 here we are publishing the same task but instead of using the for loop and if statements and append call reason list comprehension we removed a lot of the unnecessary information their brains would have the process otherwise at a glance we can see that this code is not just looping it's creating 1 list from another West that's a better description of our code actually does when you have a specific problem user-specific tool OK I'm this 1 and you can look at the slides afterwards come well we'll go over very briefly cell I essentially if you have something that has a methods of like this contains set add remove it is in the uh this is very similar to what Python objects actually do and in that way container does of any variety a list does what a dictionary does think about whether or not you should be making your own version of those containers do that with abstract base classes in the standard library or you can roll it yourself using under methods but thought about functions and this code connects to I map server and that reads the Mail tha notice that 1 of these functions return the server objects and the other 3 functions except server objects should be have something weird is going on here if you find your passing the same that the multiple functions and loving a class this is exactly what classes were line for and is a big push back against making classes an object or a programming in general but classes bundle functionality and data together whenever you're doing that you code it's appropriate to use them but OK that story have when you find yourself wrapping up code redundant try finally is work tri-accept blocks and whatever you have a cleanup step in general think about using context manager also when you making 1 list from another list is an idiom for that called list comprehension it might be a little bit of more clear to use than using a fully and when no 1 objects that looks like a container but isn't a container it probably should be a container you can turn it into a container by other methods but be afraid to users under methods used regardless of whether it's for context manager a container or anything else but method there are your friends they're not on the magic methods because they are not magical if you have a specific problem use a specific solution yeah when you're writing code stop to pause every once in while and actively consider the readability of your cup you can use these checklists as a starting point for your own reflections on your on page readability it uses checklist on you can start to build up that could style guide that we talked about earlier that I know you all have the 1 to improve and and remember that every project does need a detailed could start guide the more decisions you can offload style guide more brainpower will have left over to spend on more interesting and less trivial things and finally here's a list of videos I recommend watching at home some of which contradicts other things I said some of which support them and latent residence we did do we have a time for a 2 short questions and
at reduction of I often forgets myself as a Python Easter when I can break up a list comprehension so are there rules does Python care and what are the rules from trying to follow your example and break up a list comprehension to replace a for if statements when you can create a list comprehension out of the no more like strategy is 1 big long thing it does Python care where I split into multiple model right right so as long as if you were inside parentheses square brackets are curly braces and pi bond python allows you to break that up where ever you want in fact you can even in data coding really weird ways just of make people unhappy don't do that have implicit like wrapping is of a really easy thing like so you can break it up wherever I would recommend breaking up before the 4 clause and before they're basically before the logical components go baby the thanks very good time and we have this adjustment for goods studying but that's all there that you recommend to look at 2 then adopt around that the look at 2 1 2 other good sigh guides out there that we can adopt 2 and adjust to our own personal needs no this this is kind 1 of those who was I say not as I do situations that occur might open source projects and histogram and a few have alright well when that there is an expansion and and I minute think tank here thanks but the the