CppCon 2019: Kate Gregory “Naming is Hard: Let's Do Better”

good morning thank you for waking up for the first slot on the last day I am aware of the effort involved I appreciate it you've been to some of my talks before you know I talk a lot about code being good I urge people to write code that is good and one of the things I say is you should give things good names then I move on to the next slide and that is because the obvious question what makes something a good name it's not fit on a slide I'm not sure it fits in a talk but I'm gonna start naming is subjective and I am NOT gonna give you some kind of name generation engine that you can turn the handle off and your names will pop out I'm gonna tell you what I think you should care about so the first thing you should care about is what you name things like that in and of itself will improve the quality of the names if you think they matter because the names we give things are the only real way we have to explain what we are doing and not just in a static artifact of the code sitting there but about when you're trying to trace a bug and you say it's happening somewhere in the validation routine or do you say it's happening somewhere in v5 370 - right you wanna you want to have words for things so that you can talk to each other and you want to be able to tell the users how do we form at the I don't know higher date of the new employee well you're naming that field so it's not just in your code it's in everything you do you know this is what we don't do well consider our ai ai stands for scope found resources management you can find a thousand examples with terrible names a class called capital X and an instance of it called lowercase X all of that stuff in samples in courses but more sadly in production code but you can get better it is something you can learn to do people are not just born good neighbors wow that new hire who the names that come out of that person you learn how to name well and it starts with wanting to name well and then doing a little thinking this be clear right I do not care but Pascal case snake case where you put your underscores I do not care about naming conventions at all that is bike shed in my opinion okay this is not about should we call this class employee with a capital e or employee class or underscore employee it's really about should it be called employee or associate or employment contract or person okay of course you need tools if you want to change your mind and Pascal case everything your snake case everything your pointy-haired boss case everything you can write on a head with a tool of some kind now all we have to express ourselves is names but we often express more than we think imagine your customers come to you and they say you know that thing we already have in the system could be a coupon or a voucher or a certification doesn't matter they can end and we no longer set them up to last forever and so you need to come up with a word for this you're gonna put this word in your code you're gonna put this word in your database you're gonna put this word in reports how many people think you can use something on its expiry date very few hands usually I can have the room most people don't think you can use things on their end dates though so these are not the same thing yet the world is full of programmers who arbitrarily pick things and then don't realize that they're in coding business tools into their arbitrary choices sometimes you don't actually want an expiry date or an end date you want an expiry or end date and time and when you name it date people think it's a date when your code treats it like a date and time you get some interesting conversations some of you know this game the function called empty is that a verb or an adjective it is an adjective a lot of people think it's a verb there's clear right that's your clue that it's actually an adjective but it's not just about people reading your production code 20 years later this tweet from Nicole she's brave newbies are always brave when they say they can't follow things she says it's really hard at times for me to follow examples with one letter variables I saw this tweet and I'm like I am with you sister preach it then she went on if you're trying to teach coding maybe make it a little more descriptive or creative than just a B and C at this point I was just gonna like the tweet then she broke my heart newbies can shorten them once they feel comfortable right that's what we're doing I learned this from yarn about ten years ago whatever your heroes do you believe you will grow up to do and so what the person who's teaching you C++ calls all the variables a and B and all the functions F and G you feel like you need this crutch of calling it today's date and total price but when you're a big girl you'll be able to give in single letter names like like your hero so everywhere your production code but your samples your slide where these things where they supposedly don't matter they matter I've told you many times when you give things a good name they tell a story first we will open the file read the prices update the orders everybody's happy but I don't always point out is that names can my they can tell the wrong story imagine a class called application has a member variable called status which is up from some a new application status and we have this set function of course this is the code for set status right you all knew that I could have hidden the line of code you could have written the line of code of course we're just gonna take what we're past and stick it into status that's what said status does until one day we need something else some kind of logging auditing cashing thing and we go into all of our set functions right and we do our little weird thing and it's fine spiritually this function is still set status life is good no one's gonna be confused if they call it stuff keeps going on and it turns into this now if you're setting it to approved I don't know maybe we send them an email congratulations your applications in a group if you're setting it to denied send them in a different email now the calling code is telling a very simple story I'm just gonna set the status it's gonna set that at noon value but that's not really the story right there's a ton of stuff happening when it's approved and when it's denied and it's hidden and this sort of not exactly lie but this confusing I'm just gonna set the status to approved plus all so let's just say that set the status to approved how much longer is that then approve why are we talking in in long obfuscated sentences so we can just have an improve function and a deny function yeah we're repeating ourself a little bit cuz we set the status variable in both cases but the good stuff the dot dot dots that I can't fit on the slide that's there for us and now the calling code says approve because you know what else the calling code isn't just sitting there in an empty green meadow calling set application status there is an F right and I bet you that if is like if whatever the conditions are to be approved set application status to approved house set application status to it denied so we have an F when we come in to setup occasion status the first thing we were doing was if again to see which it was the other up tomorrow but it's not helping the reader so if I have separate of proven deny functions now I'm back to telling the right story almost two points to this example one is bad names confused the other is code changes over time that can require names to change over time now look it's hard it is you may not get it right on your first pass you may have set status at first and that's fine one of the hardest times to come up with a name is when you're refactoring I know this hundred lines belong together but I don't know what the heck they are yet I haven't read them and I know people who literally mash the keyboard right make a function call it whatever comes out that's what I did in the slide deck and mash the keyboard and then you will obviously obviously echo script give it a real name later a slightly safer approach is to give it a really really long name right this one is not really true this one says set shipping costs adjust total and Markus shifts you probably all are ready to transform that to a shorter name but it probably started life as a set dollar amount seven because there's a variable called d7 adjust accumulated number three because there's a whole bunch of things that are called a whatever and you've decided that stands for accumulated because you see a lot of plus equal action on them so it might have a really placeholder name but then later when you learn oh that's the shipping costs then you go in and you give this thing closer to its real name and when it finally gets this name you're like I could call that ship and you do true names are important but they don't always pop out right away here's the thing to give it a name you have to put yourself in the shoes of the consumer of Denis now when you're refactoring out a hundred line function the consumer of the name is you it's not even you in a year it's you in 30 seconds and it's really easy to identify with that developer you know almost everything that matters to them well then if you're writing a class from scratch and you're designing the interface of that class what are its public methods gonna be now this is for you a month from now or it's for the person who sits next to you those are both harder to think about how they think that's why we have meetings to do that kind of design so we can share how we think but then imagine that you're writing a public API it's going to be called by people who aren't on your team maybe aren't even in your company maybe you call your employees employees but Disney calls their employees staff or something what a Comcast matching here's there are lots of companies that call other people associates and so should you use their words in the API or your words in the API and as your code gets more and more generic used by more and more strangers this gets almost impossible to imagine and there's a story I like to tell and I believe I can tell this because you all know that I loved the algorithm header right there's a little algorithm header love club which has had meetings this weekend to say and you know you know who we are but I was explaining to a non C++ technical person why I love the algorithm header and here is a story that I told we have a function called sort I hope you're familiar with it in its simplest form it will take pair of iterators oft in the beginning in the end of a collection and by default put the smaller ones at the beginning of the collection so if I had a pile of integers 1 5 4 2 97 and I start them my vector let's say 1 2 4 5 7 9 yay of course it doesn't have to be the smallest you can provide a predicate so my vector might be a whole pile of purchase orders and want the purchase orders with the highest value to be at the beginning of the collection Trek if you were in Andres talk you know that sorting is expensive and sorting involves copying if I have a thousand purchase orders and someone has said what ten purchase orders are responsible for the most revenue I do not care who was five hundred and second and who was five hundred and third right that's a waste Wow the algorithm header thinks of everything we have partial signs yay so much cheaper I mean just sort in this case the first three integers and the rest of them the unwashed masses which if I had a larger screen would be your 997 purchase orders or whatever there in any old order we don't know we don't care the best are at the front and they're in order good thinking but imagine my my list was already per muted by date or by sales rep or something else was already sorted now if I sort it by value I'm gonna have to sort it back after I've gotten my information I could take a copy of my thousand purchase orders and parcels sort them but I'm paying for the copy or I could use partials or copy she does what it says on the tin it gives you a copy a smaller collection that is just the things that would have been at the front and it leaves your original collection in its original order if you have never heard of partials or copy before take a minute to be impressed it's solving a real problem it's fantastic and I love it but you have for whatever unearthly reason a vector with a thousand purchase orders in it you want to know the ten purchase orders they're worth the most money and you have never heard of algorithm but you do know about CBP reference comm is there a universe in which you will look for sort you don't want to sort your vector this is not the right name for this well it's a right name for it it's an implementers name it's a name that makes perfect sense if you're the one who wrote it or designed it it makes perfect sense if you're the one who had the problem with sort or partial sort great name I'd like to see it called top end that's the problem you have thinking about the problems people bring to your code it's really hard it Marshall how old is partial art copy 25 years at least names tell a story don't always tell the story you want I am delighted it is there that we should had another name do not tell me to write a paper I'm gonna give you some specifics but there's some overall big-deal things I'm gonna give you first you need to be consistent the most important thing to be consistent with is what your users say because you talk to your users at least indirectly and your names leak you have reports in your system and they are labeled end date or expiry date or whatever you called your thing you send people emails that their coupon discount title certification is ending expiring becoming inactive soon you have words on the screen that tell people where to click or what to type and just as you talk to other developers about what's going on you talk to your users you talk to your customers and you will use hopefully always the same words and so it would be good if they were the right words you don't want to put a translation layer in I've had this where the users are like oh yeah the developers call that whatever doesn't usually end well so a little discipline always call everything by it's correct for some definition of correct but at least by the same name don't call it revenue in your code and income on the screens and reports right same name and if you can don't use the same word for different things if you can have some things in your system with expiry dates and some things in your system with inactive dates and these things expire and these things are inactive oh I can't tell you how much easier it is when someone says my coupon is expired but I don't think it should have I can just search for expired and I won't bump into all the code around the inactive of whatever it is that goes inactive so if you can just pick words it is difficult because humans use synonyms so to be able to say you mean invalid right every time they start on telling you about some bug it's a not a beginner technique but if you can everyone will end up happier certainly make your code do it then progress to the advanced technique of making humans do it but they don't know all their words they know that things get approved or validated or paid for a shift or whatever or that they win the game and defeat the boss but they don't know the words for the pieces of it like first we do this and then this and then we know whether or not we can approve it and then we do their last bits they don't have words for those I had one client where I the business words were all human beings needs like first Stacey works on it for a while and then she puts it on Jane's desk and that they had no words for what Stacey and Jane did please don't name the functions Stacey and Jane also please don't give them dependent names what I mean is this kind of thing I found out that there's something here called load so we're gonna do load before that we're gonna do pre load and after that we're gonna do post load I see this all the time what have you told me I am aware that we read code from top to bottom right there is no information in calling these pre load and I think if the business calls on pre load okay but if you just couldn't think of a better name try harder what do you do you load are you figuring out what file to open are you checking permissions what's happening give it a name so I know what it is I already know when it is and as a extra bonus if you end up changing the name lo you don't have to go back and change pre lo and post load and whatnot to reflect that change which is a sort of thing that refactoring tools don't always find for you this one I think some of you will dislike but I'm still gonna say it I would prefer that you do not describe what your function does in your jargon but you do not update the config file but you save or you save configuration that you do not have storage coordinates you have location some of this comes from my experience with programs that are decades old literally do you remember any funds we had any files and then it moved into the registry and then it moved again and and it will move again and it will move again and if it's just called update configuration or save configuration I don't care how it's stored I don't have to change the name of the function and the function never lies if it were saying update registry settings it would be a lie by now right especially if it's like no on an iPhone and it still has that name so ordinary English words live longer but they also cause you to talk differently to each other and to the people you need to talk about who aren't software developers be able to say we were saving the configuration but this went wrong he's actually nicer than we were updating the config file but you may not do it on your first pass it may take you a while before you realize it's true name if you are a native English speaker you probably know this but I'm gonna do it anyway it's begin and end not last last goes was first its crate and destroy open and closed next in previous couldn't get and I will die on this hill source and destination not target if you're not sure it's the world's most fun Twitter poll okay and this applies whether it's a pair of functions variables a pair of classes whatever choose the the pairs that people naturally expect if you have begin and last people are going to be confused okay so go with what they're expecting let's talk about functions specifically functions are verbs and they're obviously verbs when I'm teaching like oo 101 and I'm talking about member functions I say they should be a business service of the object you know but even if it's a free function it should be a thing that your software does like I figure out what the taxes are or I decide whether or not to improve the application sometimes as an empty we're not sure if it's a verb or an adjective this is where a helper comes into play empties ambiguous to some people is empty is not I will give you I don't say code smell but I will tell you if you need no discard that is the universe telling you that your name confuses people I am glad we have no discard because names confuse people but I'm just telling you if you need notice card your name confuses people and it's not about them I'll tell you that to consider also has and can but think about whether or not you're like inventing words to use your helper is shippable like no one in normal life says is order three to seven shippable yet i don't think that's a word but we have is Knobble throughout our applications consider can ship sometimes people don't like ken whatever because of agency orders don't ship themselves so can is something you could do not something that can be done to you they want to call it can be shipped okay to ship you got lots of choices the minute you start thinking you're probably going to make a good one get ship status in my opinion should not return a bool right I want is ship a bowl to be true or false I want Ken okay to ship all those guys all those choices to be a bool but I expect get ship status to be in a new was like pending ready shipped canceled and some of those are okay to ship and some are not and the honestly the logic about whether it's okay to ship something after it's been canceled or did it well ship it when it's already been shipped to my mind belongs in whatever this imaginary thing is we're discussing and not in the code calling it ship status but that's not about what's call things but if you're gonna use some adjectives if you're gonna use some nouns and verbs now you have to think about order like we don't say tax determine we say determine tax but we do sometimes say inventory check although check inventory would also be okay I don't have a rule for you I have think about flippin you're down in your verb see how you feel about it one thing you might care about has nothing to do with your code and everything to do with how you interact with your code a lot of tools have some place alphabetical lists of functions right so if all your tax or fees or employee functions start with tax or fees or employee then they're together in those lists but if they start with update and check and deduct and then they're scattered all over the place depending on your autocomplete do you have to type the whole first half of the variable before it starts offering you others or if you have something called employee update and type update will will your autocomplete offer that to you so you may decide to keep a pattern around what goes first for tool reasons and if that's your life you need to at least know it but that's what I asked has entries and has wrists belong together alphabetically because they start has or should they be with get risks and get entries and address entry and add risk and how would you put them together like I can have risk add I could have risk yet I guess but I can't have risk has so now I have to come up with another word like maybe risks exist or something it starts to get complicated if you're going to give yourself rules to follow you and find yourself a little bit constrained sometimes and what you end up calling things now functions take parameters and they ride two horses they are local variables in the function scope so we haven't talked about local variables yet but we will and you should name them as good nice local variables and if it's a member function can I just please argue against parameter decorating I'm not going to talk about how you decorate a member variable to say it's a member variable but if your solution to this problem involves decorating don't decorate the parameter my reason is because they are also accused to the function caller the function caller doesn't know what an arc X is all right if I'm constructing a point and I see that it takes x and y I know what those are but what's arg X what's power MX all these decorations that we put there not helping the caller at all this is Visual Studio showing me the signature of a function that I'm calling I believe everybody's IDE will do this if you ask it right so it's saying that you know there's a stood string called full name and there's an int called yearly salary that helps the person who's calling the function to know what to pass to you so remember that you're writing that hint when you're naming your parameters so that was whether your functions were free or member functions but let's talk about classes they are nouns and nouns tend not to end in the letters ER or our formatter normalizer manager I ask what does this format what does this manage what does this normalize and at the minimum sorry at the minimum I add that noun into the name call it report printer call it I don't know result normalizer but very often we don't need the verb we can call it report we can call it results okay of course there are real-life managers and there are real-life printers like the boxes that make black marks on paper and if you represent that physical item in your program you can call it printer I'm not grepping for ER in your code I'm just saying if you give your class a name that's really a verb back up a minute and I try not to decorate classes I do not like employee class I'm also not a big fan of all this proxy factor adapter interface you know I spend a lot of time in the c-sharp world where all the interfaces were called AI whatever and I think a lot of us do not like that right we do have the Apple thing but I think carefully before you decorate right is an inventory singleton a better name than inventory setting aside single tinnitus and you're not writing a tuple you're not writing abstract you're creating an abstraction and the one way you know that you're creating an abstraction is that you can name it so you do not have name and address which later becomes name and address and phone which later becomes name address phone and email maybe I missed the part where we put facts in a couple years ago and then we took it out again because no one has fax anymore you have to think of what that a so that's the person's contact info that's the name you have to think about again with that empathy who uses this class what are they doing when they get one back from a function what are they doing when they create one and fill it with values what are what's their purpose for using your delightful work now classes have member variables and member functions I see this all the time employee has an employee name well yes yes it does and I know we're bad at naming right like my dog had a bowl that said dog on it and no silly because her name was puppy the only way I'm gonna let you have a function an employee called print employee record is if employee record is already a thing that everyone in the company already talks about okay but other than that please do not repeat the class name in the member variables or the member functions of the class they're already there and adjectives please adjectives are free not name full name not salary annual salary now you don't need the comments that says per year right after you declared it right and again with the decorating I'm okay I like higher date and I think it's because we talk that way but sticking string or double or whatever on the ends and beginnings of variable names and function names it's kind of strange the magic word I will occasionally be okay with his ass right so if you're making shipping labels and you have a weight which you keep as a a numeric type in the class but you have a function that get weight as string even though you like look at the return type it returns the string of course it's get weight a string but it's sort of like somehow when you put the word as in it I'm finally okay with it if you can't make me up a story that involves the word as then please don't encode the type in the function or the variable name you should know there are some names that have been written for you when it comes to member functions you should be following a traditional path and not confusing people so we'll start with constructors and destructors everyone knows how to spell these and everyone knows what they do alright and so you want to open the file in the constructor close the file of the destructor I mean not only do you have all the usual goodness that we get in our AI i but you don't have to worry about should I call this setup and teardown you know like the endless arguing we have names for that and I see constructors that call init and I see destructors that call cleanup and I just cry why are we doing that getting set you may not like them lots of people don't like them but they exist people use them people know what they mean please get when you just return some member variable set when you just member variable equals what I was just past if you actually are gonna go and retrieve it from the database or prompt the user and ask them for it I had a whole class of students who when I told them to write get employee they like prompted in order get age or something they prompted like what is the age and then we saved it into the variable because that's how you get a value you ask the user for it they can be taught but one way it can be taught is if we only use get for that accessor and use retrieve fetch load read and so on for all other kinds of getting also people expect get thinking to be Const so if you do that you're helping them and you should know about this pattern I first met this pattern one of my first external C++ projects and I instantly hated it but it has not evaporated from the face of the earth which is clearly unfair you have you have one function that takes a variable and puts that value in the member variable and a function with the exact same name it doesn't take anything and it returns the value of the variable it's you're getting your set but without the words getting set because that's apparently less confusing I'm gonna throw a news in with classes I much prefer scope to news if you have any choice at all including when you're refactoring because of course the values can be unique are not unique right so you can have all the okays you want you don't have to decorate up all your okay's with some subset of the ANU name guess what I don't want you to repeat the illuminate so trust the language and have an okay in all of your scope dnews if that's what you want don't call it f be okay and T okay whatever but when we're talking about in news and I'm not really talking about a encapsulation in class design only really talking about naming but sometimes we leak values when we shouldn't think about that class we were talking about where set status began to tell a lie the other issue with set status was in order to call it you to have the new maplocation status tapassin approved or denied whereas when you call approver when you called an eye you don't need to do that so here's another thing in the same class system it's the next application status is equal to approved again that's a lot of words then whatever it is we do when we're coming going through a collection and finding an approved application but now this calling code which is outside the application class needs to know about this Anu if instead I added an is approved function to the class the India would not leak outside of the class so it's kind of an evening question because why do we have get stats why don't we answer the questions the calling code is actually asking inside the class and then we keep our name to ourself local variables is the saddest part of naming because people do mostly oo they have some classes in their system they have a bit of a design phase they think a little bit about what to call that stuff but it's when you have the blank screen and it's time to type people just behave badly we'll start with the edge case it is sometimes okay to have a very short variable name if you are writing a raw loop why are you writing a raw loop but if you are writing or loop calling your variable index or position is not helping right that's not what's the problem with your raw loop is not that you put I in it go ahead and put I in it we all know what that is okay if you're doing scientific stuff I did some some work modeling oil refineries the temperature of anything was always called capital T it was not called temperature that would be dumb X&Y coordinates are x and y don't spell out velocity if all of the functions tell you how to calculate V okay that's about consistency with user nomenclature again and then there's what I call the pronoun case then if you're talking about me the first time you might use my whole name the second time you might just use my first name then you eventually just start saying she in some very small scopes a very small name is okay it can be a signal that this is a very small scope so in this little sample code we have a string which is just called R which stands for something related to responses it might be response singular plural response list response string who knows what it's real name should be it's a very very small name and we immediately leap loop through it and strip things out of it until it is empty building something called responses and if from here on we never think of R again and only work with responses then this name sort of carries that information says this is just a very local reference that we'll never have to remember again it's never wrong to give it a longer name but it may be okay to give it a very short name in this very tiny scope signal and for people who are super disciplined about names they can send you a signal by doing that but the truth is that the vast majority of names should be much longer than they are today they should be nouns with adjectives next current remaining active you know why you were doing things don't make an employee e right if you haven't told me anything tell me what kind of employee it is is this the new hire that we're creating to add into the system is this the imaginary one that we're using to put on the demo screen like give it a name and that usually means an adjective people love to say next employee current employee active order and that's okay but don't encode only type that would be over decorating I don't like employee or double D but I also don't like vector of policy policies like I again have learned nothing right why are you building a collection of policies are these the ones that need to be processed that are pending that are expiring this week tell me why you're building the collection and you'll know exactly what to call it and especially when it comes to simple purling if you're the class called employee and then you make a variable called employees with an S on the end how does anyone find that when you call it active employees they can search for active when you have 27 different things with the word employee in them but they have other things in them we will find them but if in 27 functions you just make a local variable called employees it's exactly the same thing every time really hard to to grep for so think about people searching for your variable names or for a fragment of your variable names the more different your variable name is the more context-specific your variable name is the more easy it will be to find when you forget where it is but you remember it was something about setting the expiry date that's better if there's only one place where we talk to expiry dates I don't like reavie ations he'll allow ID I don't know one says identifier everyone says ID but like DT for date and things like that what's wrong with you vowels are free first syllable only sounds like a great idea you know we can have annual revenue could be an Rev or a our total income could be tot ink or TI revenue difference could be revved off' or Rd I hope you agree that the first letters is like write only write like you knew what it was when you wrote it down but later you're like what is what is Rd I seem to be subtracting two things and like five minutes later you figure it out first syllable is not much better okay you may think it's obvious that taht stands for total other people do not and yes vowels are free I have worked in languages with lens limits now I don't coincidence if you're jamming five or six words together name address phone number right maybe you need to take it up a level but in general don't abbreviate anything and longer is better have to briefly talk about templates because this is C++ everything about templates applies everything we've done so far applies to templates right you're writing a templated function you're writing a function name it accordingly you're writing a templated class you're writing a class name it accordingly but we have the type name thing the compiler no longer cares at all from 17 odd about type name versus class I know temper pimp with my robot but no some people care tremendously and they all have excellent reasons for it I have heard classes less letters to type I have heard classes way overloaded so I try not to say it especially if I'm writing a templated function because people see the word class and they think I'm writing a class okay and I've heard this one I say type name if I work with fundamental types like integer I don't need you to have member functions and I say class if you actually need to be a class and I'm counting on you having a particular member function yes yes concepts but we still have lots and lots of templates to deal with if you want to have some kind of signal like that go ahead and have that signal but be aware that is a very very weak signal and other people may not know it but what do you call the things all right class T type name t only one yeah I'm good with T thank you I'm good with T its traditional in fact if you call it something else you might confuse people but the minute you have to you've got to be meaningful I know T and you T and V we all do it we have to not I went into Microsoft's STL because it was easy I had to right-click go to definition this is basic string it has three it has LM traits and Alec notice it's not the first syllable it's the first two syllables and given what happens when you get template error messages I'm in favor of five characters instead of 73 characters so I'm going to say okay but it is notice it's not e alum it's not tea its traits so that you can follow along and the same here with vector where we have ty4 type Alec for Alec air so follow your heroes do what they do don't have T in you it's a good question right when do we name things probably you're saying it depends but that's not true doesn't depend at all there's only one answer when you know what it is now yes sometimes that's on paper or a whiteboard you know right away you're designing something we're going to need an end date we're gonna have to calculate the taxes we're gonna need the taxes right you know the names other times you've been reading something for quite a while and you go I just figured out what our D stands for in that moment fix it you have just learned it's true names revenue difference or whatever it is Holle out your favorite refactoring tool and fix it on the spot remember a name that used to be right may no longer be right when you realize that when you realize that you don't really have a bug you just had a mental problem that you thought set status only said the status change set statuses mean so that it doesn't make people think it only sets the status because I work with code that lives for decades and it constantly changes what it does it not often enough changes when it is called and is the best gift you can give as a maintainer don't just fix the bug or add the functionality update the names well that means then if things don't get their original name their true name when they're born that they spend some time living under a temporary name this can also happen when you're refactoring or when you're writing it from scratch so how do you make sure it gets its real name I'm gonna give you a grandmotherly piece of advice there is nothing you can type into your code that will cause you to give this a new name later nah think nada to do comment not a deliberately horrible name again at the script not a swear word not a remember to rename this name nothing in your code you have some way of living your life outside your code right you have a to-do list you have tasks since them to do tracker you have a piece of paper on your desk you have sticky notes Trello boards maybe you have JIRA you have a thing and if you know this name is not right use one of those things that are outside the code so that you will remember to come back and fix its name okay I know you believe that if you put the right thing in the code you will see it but here's the deal you would fix the name if you saw the name right and you're not gonna see this comment or anything else unless you're seeing the name so the comments not adding anything you need an external reminder but in case your external reminder fails do not call your function stupidest thing ever or proof that bill should not work here you know they joke about consultants that we borrow your watch to tell you what time it is there's a thing about the consultant you winds a sheep off of someone by knowing how many of them are in the field that kind of stuff whole Paula jokes about how consultants don't tell you anything you didn't already know and I'm always like you're walking around with a watch on and you don't know what time it is clearly you need a consultant I'm happy to help when I come into teams and I make them give their stuff good names it makes everything better you might not expect this it seems like a party trick it totally works you know you know about that 5,000 line function with a vague name right maybe you have a 15,000 line function with a vague name nobody knows what it does what this process do oh you know it what processes everything really we'd be lost without it this for most of our bugs are it's very important but if the friendly nice consultant comes in and says I'm sorry I don't know your business process is super well and I find process kind of vague can we rename it to what it you know really does wonderful things happen because nobody can name it because nobody knows what it does and it's too long and they don't understand it and before they can give it a name they have to fix everything that's wrong with it it's a simple gentle request that fixes so much one reason things are hard to name is that they are the wrong size this is very true for classes they are too big too much unrelated junk or they're too small it's just a handful of dumb little attributes they don't really have a name it's less true but it's still pretty true of functions so when you say I don't think and one is a good name for this sometimes they have to completely refactor it into something smaller or bigger in order to be able to give it a name I want code to tell a story code can't tell a story when your doubles are all called d1 and your employees are all called E and your functions are all called process and calculate and do it who's written to do it the rest of you are just ashamed to admit it when you want a story the only way to give you a story is to give you the names that's what I want you to go out and ask for in your life start by caring care about the code you're writing care about the people who are going to read it the people are going to maintain it and the people whose lives it is running for that matter think about the purpose of naming this variable this function this class this template who calls it what do they use it for they really want to partial sort copy or do they want to find the top ten purchase orders if you can't name it that's okay give it a name fix it later never miss an opportunity to fix a name when you name everything well your slide where your samples your scribbles on the whiteboard everyone will start to do that and everyone will benefit from that as you're going through code that's not right you learn what it is fix its name it change what it is change its name keep everything synced up because names matter and if you remain consistent within yourself within your software but also within the larger world you will end up using the right names so your code can tell the story that you want it to tell because naming is hard but we can and we will do better thank you remember a question is when you want more information from me thank you I have a question about I'll actually have two questions one is about things like returning having beans that when your function returns the thing is specific unit for example um if you're not using like strong typing to be able to return kilometers rather than calling it get length I would probably prefer it to be called get length in kilometers yes it is a little bit of a decorating and it's probably true that the better solution would be the strong typing kilometers type but if that's what you can do today get length in kilometers is better than get length the other question is about your example is shippable yes I understand that like he's ready to ship is probably a better name but given that we're all programmers here and the person is reading the codes a programmer wouldn't use shippable really communicate it can be write like I'm not ever saying don't do this do that you I really only want you to think and care but I want you to imagine someone phoning in a bug report and you saying well that's because it's not shippable yet if that's not a conversation that works for them and they say English please then that was caused by using internal jargon in your names because probably the big inside I have for you here is your names leaked right so keep that in mind when you're using them your employees list of employees was quite compelling but what if there really isn't any other name like for instance if I have a train and it's got a list of cars what would I call it other than cars well you don't necessarily need to call it cars in this train I suppose but it could be called attached cars cars in use there could be other words for it there's going to be times when you really have nothing to reach for build a plural but I would like people to notice the 90% of the time when they have more than plurality to put into a new um sometimes when searching for the right now in a verb I've found using these sources or reverse dictionaries to be useful as underneath or other kinds of resources that might be useful for that sort of search that's an excellent suggestion I had a misspent youth involving on every book in the library and so I have a huge vocabulary if it's difficult to come up with synonyms I think going to online resources to find more synonyms a great idea also asking your co-workers or the people that you're going to discuss the code with thanks for see this is about decorating right it's still really the same question as should I call it blah blah blah blah adapter blah blah blah blah proxy and the answer is it depends when you imagine someone using your code is it obvious that it is a special kind of map or will it help them to put the word map in its name if it's obvious or not relevant then leave it out if it's neither obvious it's not obvious and they need to know it then leave it in there thank you you talked a bit about a search ability and about the conversations that developers have with each other using the names that we come up with and both of those are two completely difficult in our code base and we found that sometimes when trying to change a name from something that it is to something that would be better we lose a little bit of that find ability and that shared conversation do you have any thoughts on that trade-off and things that might make that a little bit less painful I generally I'm encouraging people to make names bigger right so if it used to be called v1 and you'd decide to call it to update versioning that should be easier to search for right but if you're changing the name in a way that takes away information perhaps you you do so really mindfully especially true if people call things by the wrong name all the time I'll give you an example once upon a time I worked for a company I was coming in as a contractor to add a piece that they needed and one of their stars had written the most important part and he couldn't spell the words separate and there were classes there were functions separate was very important in this system and it was spelled wrong and I said should we fix this no no we all know the search for the misspelled separate and if you fix it we will never be able to find it because we have all learned that that's how we spell separate here so sometimes did the bad name stays for that reason oh wow I would almost never go alphabetical although I understand the reasoning it actually I had two answers at least and maybe more if these are simple like report type right or screen number or something it doesn't matter at all what order they're in so you want to put them in order they can be found alphabetical is probably the way to go and yes that will change the numerical value on the next bill but who cares no one's counting on the numerical value but many times are in neumes are kind of like a state machine do you not I mean like it's pending and then it's approved and then it's completed and so then I want them in that order okay if it's a set of error codes I probably want to lead with okay and then go like mildest to most severe so there's a lot of have a reason don't just always stick the new things at the bottom like put it where it belongs but have it makes sense and have it so that the next person who comes along will know exactly where to put their new value thank you you were speaking about naming insight functions like classes and templates in artwork we have like a little section in our wiki called what's in a name which is essentially an apology for what four modules having code word names like McKinley or something what what is your spots on leaving at that level coffee let's do that I'm sorry for asking that question I'm gonna say thank you we'll talk on the one thank you [Applause]

Channel: CppCon

Views: 27,149

Rating: 4.8764043 out of 5

Keywords: Kate Gregory, CppCon 2019, Computer Science (Field), + C (Programming Language), Bash Films, conference video recording services, conference recording services, nationwide conference recording services, conference videography services, conference video recording, conference filming services, conference services, conference recording, event videographers, capture presentation slides, record presentation slides, event video recording, video services

Id: MBRoCdtZOYg

Length: 59min 35sec (3575 seconds)

Published: Tue Oct 08 2019

Reddit Comments

[u/voip_geek]

Looking at you, std::monostate. (and you too, std::remove())

[u/RomanRiesen]

"naming requires empathy"

I might quote this.

Maybe as "writing code requires empathy". That sums up so much of applied software engineering very succinctly!

[u/warieth]

In C++ the constructor and the destructor has a name, but these name are not used. C++ uses the class name for the constructor, and overload it for completely different uses (copy constructor, move constructor). The special member functions all have a name for teaching. I would have no problem if the move constuctor is not an overloaded constructor, but having a name "move_constructor", and "copy_constructor" for the copy constructor. The two names are easier to read, rather than counting the reference characters (& or &&). This would help correcting the code, if the programmer uses the wrong reference type.

[u/mje-nz]

Another great talk from Kate Gregory; slides are available.

[u/Tumperware]

Kate is great

[u/sim642]

Without watching the (hopefully great) talk, first my mind went to: naming is hard, let's just not name things.

[u/VinnieFalco]

There is nothing wrong with

for (auto i = 0; i < a.size(); ++i)  
    ...

[u/epiGR]

I didn't get much out of this talk since most things discussed are obvious to me ¯\_(ツ)_/¯