The Other Hard Problem: Lessons and Advice on Naming Things

Video in TIB AV-Portal: The Other Hard Problem: Lessons and Advice on Naming Things

Formal Metadata

Title
The Other Hard Problem: Lessons and Advice on Naming Things
Title of Series
Part Number
21
Number of Parts
46
Author
Contributors
License
CC Attribution 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 purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Identifiers
Publisher
Release Date
2015
Language
English

Content Metadata

Subject Area
Abstract
There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton This quote finds its way into many-a-talk about caching systems (including my own), and sometimes we as developers will recall it when we spend an hour to name that one nebulous variable. But why is something so difficult as nomenclature also thought of as too simple to actually talk about? In this talk, I'll review what has been written in the last few decades on naming, go over the easy parts of right or wrong as defined in PEP8 and other style guidelines, and finally suggest some patterns and anti-patterns found in in today's Django and open source environment for us to adopt (or avoid!) in our everyday naming of variables, libraries and other "things".
Group action Presentation of a group Multiplication sign Time travel Student's t-test Revision control Programmer (hardware) Positional notation Energy level Software testing God Covering space Dependent and independent variables Inheritance (object-oriented programming) Software developer Gender Gradient Projective plane Electronic mailing list Stress (mechanics) Bit Numerical analysis Degree (graph theory) Cache (computing) Process (computing) Computer science Moment <Mathematik> Video game Right angle Quicksort
Point (geometry) Functional (mathematics) Dependent and independent variables Code Consistency Electronic program guide Bit Computer animation Radio-frequency identification Video game Quicksort Family Social class
Frequency Arithmetic mean Code Natural number Multiplication sign Electronic program guide Software testing Numerical analysis Computer icon
Arithmetic mean Dependent and independent variables Word Well-formed formula Interior (topology) Real number Bit Right angle Formal language
Hardware description language Category of being Building Block (periodic table) Computer programming Translation (relic) Bit Parameter (computer programming)
Point (geometry) Domain name Context awareness Code Chemical equation Bit Data dictionary Variable (mathematics) Disk read-and-write head Arithmetic mean Word Data management Mathematics Voting Personal digital assistant Different (Kate Ryan album) Single-precision floating-point format Website Endliche Modelltheorie Musical ensemble Quicksort Descriptive statistics Spacetime Social class
Functional (mathematics) Dependent and independent variables Code Direction (geometry) Multiplication sign Bit Line (geometry) Lattice (order) Mereology Word Personal digital assistant Endliche Modelltheorie Figurate number
Word Uniqueness quantification Projective plane Right angle Cartesian coordinate system Food energy Family
Word Computer animation Code Hypermedia Consistency Planning Software testing Line (geometry) Mereology Cartesian coordinate system Code Field (computer science)
Point (geometry) Trail Context awareness Implementation Open source Code Multiplication sign Control flow Design by contract Rule of inference Programmer (hardware) Mathematics Goodness of fit String (computer science) Software testing Metropolitan area network Social class Motif (narrative) Dot product Electronic mailing list Variable (mathematics) Connected space Personal digital assistant Universe (mathematics) Quicksort Figurate number Writing Arc (geometry)
Point (geometry) Context awareness Group action Open source Code Multiplication sign Modal logic View (database) Control flow Branch (computer science) Insertion loss Mereology Fraction (mathematics) Meeting/Interview Term (mathematics) Videoconferencing Software testing Endliche Modelltheorie Extension (kinesiology) Inheritance (object-oriented programming) Validity (statistics) Information Block (periodic table) Projective plane Physicalism Plastikkarte Flow separation Type theory Message passing Word Data management Arithmetic mean Voting Commitment scheme Video game Quicksort Spacetime
what are the kind of the time and the and and the and the and the mn listen to give a talk yesterday on the intersection between humanities and technology specifically how persons as an English major influence and helped her life in the tech world I'm an english major as well and as as soon as I saw all the abstract I knew there was going to be a pretty big section of between our talks and so we talked and plotted things out and the clueless another wanna take from her is that there are soft problems cough and technology that we can use the lessons from from writers lessons from your English professor lessons from your high school English teacher and to make us better programmers but didn't catch talk please put at the top the list of the to re-watch once the videos on demand go up it was a wonderful talk and a lot of people think people both from humanities majors and people from the more technical background of a lot to learn from it the the the person I wanna take away is that there are hard problems in computer science that our not solve that heated up by the lessons we can take humanities and present that I wanna talk about his name the new variables only the methods names of projects and make that the so as the gods that Lisa covered yesterday and needed important because there what we leave behind as signposts to a fellow developers and both cannot developers people were you coworker co-workers of people who made work with you later in you 1 year from now you want yourself your own self to have names things correctly if you do not future you will be mad at you and that is how time-travel movie stars immunology the protagonist in that movie a ecology number of reasons why you wanna have been and other than to avoid being killed by yourself and causing some sort of conflict but numbers those kind into the actual advice on later in the talk the students mind is Jacob Jakubowicz the name of becoming a workforce versus the name of my title is developer I guess and that the name of this talk is the other hard problem the a you probably know the name the torque is referring to so there's a quote begets battled around I used in and talk here gender that 3 or 4 years ago and when I gave a talk on cache invalidation and catching within gender with my covers co-presenter no silence there's a quote there only 2 hard things in pure science caching notation in naming things know the arbiter of job versions of this but this is the 1 that matters and it's someone in its own right right because you have this super super technical thing Cassia knowledge and hard CS grads have a really hard time with that you have the super soft problem in naming variables and that's kind of funny that the 2 polar opposites of our discipline and still the height is highest in difficulty at least was going this quote and a group of that because that means my American literature degree was not gone away so I can use it in my professional life even if it's just to give this talk 1 1 at a time could go on and talk about on this is a novice level course so of loving all the same may seem self-evident to some season developers here but a common stress and obvious restress throughout that a lot of mistakes here are not mistakes of ignorance the mistakes of laziness it's easy to do the easy thing and on of your life even if you know the better that so that you think this is sort of step to talk and in that it's not I expect you to have a little bit about them and that they hit you interlaces talk maybe read the happy thoughts on that so cover peppered a little bit with a special guest instructor that all introduce a little that is new some tips on meaning other variables and then I have a few notes just on how we can take these lessons in apply them to our test and documentation so to the steps in the
pit they i wanna actually quote verbatim from leases talk she's talking about their own style that English style guide and by something like the brother point of about Strunk and White though is that this is the guy written to help people right clear and more concise more consistent more readable English had 8 is a guide for helping people right clear or concise more consistent and more readable code and that bears repeating the works exactly the same 4 names the point of our names are the signposts in we want them to be clear and more concise more consistent and more readable so legs
and really breeze through Pepe and what it has to say about naming variables and even if you haven't read that they they got a visa appendages read a little bit of on Python code that's written in last few years the last decade we all upper CamelCase class things we lower and underscore our variable names are method names the function and we show at the top of our lungs are consonants there's a few selling lesser known advice as well I so we add a on 1 score when we won the kind of suggest this is a private method that name may or may not get maintained we have a double underscore to reinforce the idea that the private method and by will invokes some name mangling again I read prepared to learn more about that and if you sort of Holland by the longest courses in the note saying magic method that you somewhere else in the life of the class this the this is a guest
post uh Mark Twain so at that time period and and with Mike and so on With the hedging Austin hoppiness guide us through tests and through Pepe and through the importance so that I could mark twain for a number reasons on 1st is he's an American master to kind of composed that go against the juxtapose the British nature background of Jane Austen he has any known for his simple elegant straightforward style starting we all appreciate as Python use those in the other room mean face a lot of bad you not know there's a picture of him smiling this pictures of him as a baby is not smiling In the 2nd these you do the code review with and you don't want to come off like is the guy who have vengeance on you you about variable names the name and I picked Mark Twain is he he did Jane Austen that I I'm I'm not kidding about this and I have seen the things
that he said about because I've just been mean and cruel I'm I'm I'm above that but he kind of wanna icon on the trade fix
this so that would be 0 the formula if you google Genossen my twenties you have not but some but I can fix this I in real Jane Austen style I wanna marry off I mean all Mark Twain about to Jane Austen arm-in-arm and have the guidance to to nirvana of Python meaning and how the having both us in both aspects of it
so the 1st bit of advice on how to has for us is use plain simple language in short words this easy right like we can directly use this in as advice and in inner variables on I yesterday at the there's a comment at interlaces talk about can think of an example the show and what not to do what violates this the the comment about not using docstrings leisure about the name which is brilliant that's exactly how I
wanna put it so this is a good example of that user about example you see this and you think I would ever do that and that and that's not me I know better I use nice concise descriptive language industry but this is a very silly example but I think there is another bit of advice where mediating we define a trap not even notice it this is 1 of the well-known Mark Twain
writing devices which is when you catch an additive colored but to nouns verbs these are the building blocks and very very spare solutions using adjectives and we read this somewhat well this doesn't translate program where we don't use really adjective maybe properties maybe arguments before work now and is kind what we stick to but it is very so look at this moment and
mono no in this case but when using music and vote that added and that it would be so much better if we just had 1 word to convey this as a couple techniques I wanted you to use when it comes to fixing this 1st thing guess 3 the 1st is when you notice that you're doing it you shall be words together to create a new class space what the about the go off your head the moon to fix it using the something on it doesn't mean it's about variable names that means there is an opportunity here to be better and to be more concise the 1st technique we can use to actually fix it is what we just got rid of 1 of the words do we lose the actual meaning I find this happens a lot with models and especially if the user model so many things that are related to the user so we add user to it there's no such thing as in this case is non user of a collection so we just get rid of the user we have just as valid so just as descriptive but a little bit shorter and it matters when you start adding manager 2 things you 2 things really helps the code states sites this another technique that's not quite as easy as if chopping something off and that's if you can combine 2 or more words to mean to 1 single word different word someone the dictionary of all the thousand thousand English words that means and then this the harder because of the problem vocabulary and some changes Google so that there's a new word and even if there is a different where does it mean you should use it town it's a word that's not kind widely understood by the people you're coding with he still should use it luckily for us book collection in this mythical reusing is or these called on and this is probably a bad example I have and this is the thing that the most people don't do because it's hard you have to think you have to put nearly nothing that much of the put in the effort of Google like MIT is the domain where that I'm not thinking of that I could be used the the so and go back to that unless the device that point had
for us because this is actually not the complete quote when it gets quoted this usually see but it's not the complete 1 this is the complete 1 when you catch an additive kill it no I don't mean that utterly become most of the rest of them will be valuable and this is sort of between way of saying context matters not going to play role universally don't be combative you have to balance things out you have to balance conciseness with descriptiveness and I want to make it clear that every little bit devising give you again because of your head it's not universal not limited device that would that we have to take context with
us is do not commit necessary details this comes up and kind of a silly example when you
use big words and because you're not sure the time with the method is actually what target direction and BCG valve forget it on most of us were no not to use something like this but maybe there's nothing like this even before In this case you know maybe there's 1 line after this where you return the response of a request so why bother why bother calling it and trying to figure would g actually is because any kind weird it's parts of your all your appointments there's no kind of like Nice concrete words so I bought all just the on and that's that's fine until you notice that need nothing to get work done by someone else and that in that case d is only the 2nd worst variable names of that will be contained in this function because the worst variable name is due to and and you can see how the 2 starts compound in this but I can almost guarantee everyone of us has done this meeting not recently but we've done this and it's really attempting to do it routinely do and test code model to that a little bit on because it's the 2nd example of something I don't I don't wanna think about how it changes how it's different so just move on the the so movement to another 1st next don't let fluff and flowers and
verbosity Creek what so that means the don't acute variable right there very will and considerable all day long there is so it's take it can be really tempting to make a play on words or upon our cultural reference uh whether a variable names is a really common may not super common but more cop most common in applications radiator project and maybe that's cheating named and that's fine because I want you project name to be marketable to be searchable TB Unique says the guy at the conference in Minister gypsy guitarist but beyond that keep to the more don't be cute and if you need to show you creative energy shortly name your project thing that
you have a beautiful baby boy you need a market and that's it is needed so that that the family name we don't go the way to name his hair or his mustache this is his mustache you don't know if you need a keep on that so you know less about the markers for us in kind encompasses everything that I would use
the right word not at 2nd cousin uh this kind comes up everything use the correct word as like as descriptors it needs to be as brief as it can be used the right word but I think this has another semantic panic comes in a plane that comes up with
consistency maybe up again you they going to do this I have a name for your else and that's the 1 I use the media to project where they were using URI when they will that URL well your hand and change the coding might break things undiscussed is the correct 1 and someone down the line says well now using your eyes a new world so let's just watch seizing address but again I'm too lazy I want that field which is key going on now now you have could the total parts the code that's further refactored is you have to search for all 3 of these and it's just not as pleasant as just saying this is what we're using when we see what someone else use before and that's what I'm going to keep on his that wasn't talking about the application code but in this talk and the I we again search 1st if the and get that and the it's important uh the test test that mutations are different and we should treat them a little
differently I think for both cases of verbosity is is less of a sense this lecture I think it completely fine testing its super verbose you would never have a method in an actual class a review named this but I'm I'm quite all right with it as a test name because you never really invoking this ever after I can imagine a place where you are so the only place for using its true the chapter title and when you're reading your Chester someone else's review as the test fills the points you exactly to what's going now that said because it can get a break the rule in a test means it's really easy to just use the R and s into short short aligned with who they're gonna read this half but people well people need change test may only the introduce another variable the sort of an arc that is the explicit and you can doesn't take that much more time on an inch it's worth it to not use something like foo and bar and bat as so about foo and bar and bat is
stop using the fact that it's not it's not uh I own F 0 0 . net so I love the sorta lineage in that connection and making programmers with some of you in st especially specialist of union documentation there so many bad examples and documentation where it's written by the barber who knows the code so well and we know something as frivolous and they just wanna show some implementation detail on it doesn't matter what the context is and low so class through defined bar in mind as a string or something stop doing something come on who does isn't as experiences you don't know why you would wanna do this and once a really good concrete example agenda dots are incredible at this they have common motifs the track title artist things and the contract the documentation is concrete universal it's something that's really well known so the can his own kind 1 that is that this has been very for general advice on the marching quotes a figure Austin they help you we have a lot of other nitty-gritty advice on how to write good variable names in chapter 2 clean code by on about Robert Cecil Martin is really really good at this has a laundry list of rules that you can fall on I highly recommend of buying a book and reading it also be linking to a source when I publishers talk on get that kind of some summarizes that chapter to get you started but you should know what man by the book and that's all I have it any questions
and so we have 5 minutes for questions the OK so I just the 1 comment and 1 question took of my kind as regards to the example used of the ballot versus those collection and that simply that I mean I I will words of the mean of the subtleties of them but like in common with Merck prone about what people think of is the thing about is a card stock of the bubbles it along with the blacking and with that you know can the names on so it's like there's a actual I think there's a a clarity and book collection that's unfortunately is a loss common denominator type target so I mean I like purchasing completely agree with you but then that I also understand why that that that final the transition doesn't occur very often on the other thing of the national question was on the time judgments is with or you can change the method calls in the to the to the screen beyond and so often times if you want their break that out and you can do that to a certain extent with some you know these inventions you know that's fine inventions but sometimes you would really do you have a variable is just a throwing the it doesn't mean anything other than I want to assign this blob of stuff someplace such that I can then do additional work on it and add clarity in the separation of what's being done but it's not necessarily carried over variable something so what is that on the common 1st and I will defend even know about it may not be representing an actual physical ballot and indeed is another word for it but as long as that is you or models tend to be offered through or starting blocks for Ferndown's thereafter views and managers are named after the model but I think it's OK and once again don't be cute but it's OK to injured be a little on metaphorical when it comes to naming those things because if you're gonna be using valid everywhere you can introduce this is what about this for us it is a collection of votes on and you can kind of set that stone and hopefully your documentation and say that valid is yeah that the that sure of and just get it on my part from for the video he was saying that there is such a thing as valid as a physical thing and it means something on I would say that the it again it depends it's contactual if you're if you're you ever care about that physical thing you know you never actually talking about altered spying on that on on the question itself I would say do your best and when you do those thoroughly there will still need and can't actually you may end up using that variable and edit later on it's also important dividing the test breaks the throne PDB you know what you're like what was this before I did select related where prefetch weighted and then you know when you can actually help it out on and prepare for edits and prepare for dividing the thanks for a great talk i um aid goes to the sort of Ballard example as well for the and like we work in a community with a lot of non speakers as well what ideas thoughts around that sort of thing of clarity for non-native speakers that maybe don't have that level of vocabulary sure this is and when it's that a hard problem and it it depends entirely on your audience I think all open source it's especially hard and I think you do end up to cut using this compound names that are hopefully avoided but that said you know it also think it's necessary in the world that if you just if you say your life it really is valid you know it's not a physical ballerina use ballot I and I would say if you document well both within the code and within your documentation that this this is a metaphorical term were using so we can keep things concise and concrete and easy the parts a big problem of you go collection is you have to read all 3 words for you know you're talking about versus what you see below you can kind of contractual it like that but it's hard sometimes you just have to give up the coast and not use a word like that I wonder she might have words of wisdom on commit messages so this is going to be completely do as I say not as I do I and and tell adds little literally 2 months ago I was probably the worst on connect brighter because I will work on projects by myself and I went up who cares so you might have a future me that's that there is little in the back of my mind I am looking through year-old code and it says fixing bug-fixing bug-fixing but and I got my idiot and this is a really good but was the can now a month or so ago and on I really like that keep your subjects super short I think they get recommendations 50 characters like little over on and then space space and then a huge as she do the body aging and again in its context dependent here just 16 about the subjects fine but it's so you know emerges feature branch merge right as much you can like even if your copy and pasting doc score you copy you copy and paste the commit message in the docks it's not and more information can commit messages in a bad thing I'm sorry the common that's not my comment this get out so you know was broadly defined and poorly named it is too late to fix a particular point 0 that we should really think you should know that we're going to do that what if you don't think you can do that yeah the other Geyer the real Jacob AS a common that what everyone's OK so all the time we have says the crown further Microsoft winners being announced and charm and we find that the only things
Feedback