« All Episodes

Folklore In Your Code

Published 2/27/2017

In today's episode, we talk about a characteristic of code that should throw a warning flag: when you tell a story to describe your code.

Today's episode is sponsored by Rollbar. With Rollbar, you get the context, insights and control you need to find and fix bugs faster. Rollbar is offering Developer Tea listeners the Bootstrap Plan, free for 90 days (300,000 errors tracked for free)! Head over to rollbar.com/developertea now for the free 90 day offer!

Transcript (Generated by OpenAI Whisper)
Hey everyone and welcome to Developer Tea. My name is Jonathan Cutrellan in today's episode. We're going to be talking about folklore. When we say that one of the hardest things in computer science is naming variables, it's actually not an exaggeration. Now it may sound like it's kind of a joke, right? It sounds kind of sarcastic that naming a variable is really difficult. But the reality is most of your code really is names, names of messaging, names of variables, names of classes or functions or methods, names of objects. All of these things, depending on what language you're writing in, some of those may not necessarily apply to you. You may have modules or you may have mix-ins. There's tons of things that we are having to actually give a name. I want to teach you a method of making your code more maintainable. That's based on some experience that I've had writing code both in a solo environment on my own and also writing code with collaborators with other developers. This is really what it comes down to. When we talk about maintainable code, we're talking about code that can be passed from my hands to yours or from your hands to another developers. It can be continued forward. You don't maintain code by putting it into a silo. You don't maintain code by only having one developer that continues to work on that code. The most common response that I hear from this is that if this is my own solo project, if this is my project and my project alone, then what's the problem? I don't have any plan of passing this on to another developer. Why should I care about whether or not another developer can understand my code? In the simple answer is there are very many things that you will build today that you will forget even as soon as tomorrow, but certainly as soon as one year from now. If you plan for this project to go any longer than even a month or even a week, then you should probably consider yourself in the future as if you are a different developer. In that respect, the working memory that you have of a given piece of code, of how it works or what it is doing, it has a termination time or maybe a better way of explaining it has an expiration date. Anything that you remember, the specifics of a given piece of code, especially if it's procedural or if it's not particularly relevant to the overarching thing that that project is doing, if it's something small, a small feature set, or if it's particularly clever code, this is the kind of stuff that becomes very difficult to remember why you did what you did, how you did what you did. One of the marking characteristics of maintainable code is that it can be passed from one developer to another and that includes from the past version of you to the future version of you. I said we're going to talk about folklore today and hopefully our initial discussion about naming will help you understand what folklore really is in code. Then we're going to talk about how we can eliminate folklore. But folklore happens when you have a single developer or maybe a group of developers who have worked very closely together or are working in tandem next to each other talking out loud when they're developing code. Now why does folklore happen? Well, the signs of folklore in your code, that's what we're going to talk about in just a moment. Folklore happens because you're talking about the code. You're having discussions about the code and that maybe internal dialogue that you're having with yourself or maybe it may be notes that you're taking on a notepad that don't necessarily get shared with other developers. The folklore happens about the code. It's kind of the meta discussion around the code. And this may seem to be a very simple aspect. It may seem very natural actually. You will have discussion about code. You will have internal dialogue. You will have arguments between you and another developer, positive arguments, constructive criticism. You're going to have all of these things that swirl around in the meta space of that code. So we're going to talk about how this actually affects your code. How it actually affects it in a bad way. We're going to talk about how to eliminate folklore right after this quick sponsor break. Today's episode is sponsored by Rollbar. With Rollbar, you can catch code errors before your users do. That sounds like a pretty good idea. Dealing with error sucks. We know dealing with errors sucks. We deal with errors at whiteboard, for example, we can have an error that occurs at 455. No one else has the responsibility to deal with that error, but us. It's not really fun to have those things spring up on us. I'm recording this episode on Friday. It's not really fun to have an error spring up on us at 455 on a Friday. In fact, that has happened to us even as soon as today. Being on users to report errors, that's when this becomes really frustrating. We have users reporting errors at all times, and they expect them to be fixed pretty much immediately. Rollbar works with all major languages and frameworks to eliminate this guesswork. So you can start tracking production errors in your code in minutes. You integrate Rollbar into your existing workflow, and you send errors, you send these alerts to Slack or to HibChat, and you can link up your source code from GitHub or Bitbucket or GitLab and convert errors into issues, in tools like Gira or Pivotal Tracker or Trello. All the things that you're already using pretty much. Some of the big customers that are using Rollbar include Peroku, Twilio, Kayak, Instacart, Zendesk, Twitch. These are massive, massive companies, and they have errors just like you do. But they rely on Rollbar because it helps them catch these errors that they didn't catch when they were building the software. They didn't catch it in their tests. They have a lot of good practices. Even the best practices, this is kind of a side lesson here. Even the best practices are not going to catch every error. So relying on users to report errors is not a good idea. Digging through log files, trying to debug the issues yourself, and a hundred alerts are flooding your inbox. This is not good. And Rollbar helps to eliminate it. Go and check out what Rollbar has to offer to you today. Head over to rollbar.com slash Developer Tea, rollbar.com slash Developer Tea, to learn more about what Rollbar has to offer to Developer Tealisteners. One of the sources of errors that you're going to experience is a misunderstanding of the intention of your code. A misunderstanding from one developer to another, a misunderstanding of the intention of your code. Now this is why naming is so important, right? It's one of the reasons my naming is so important because a name carries a lot of value. A word carries a lot of value. A title carries a lot of information. The attributes on your class instance, for example, those carry a lot of information. It's important to name things properly. But here's the thing. Learning is so hard because we all have context and we have to learn what a name actually means. And this is where folklore comes in. And so I'm going to give you a very simple way to determine if your project has folklore kind of helping it succeed, right? If there's folklore necessary in order to understand how to work on your project. If you as a developer who is working on the project, if you have to explain what a class does, if you have to say, we're calling that X. And really what may mean is why, right? Or if you have to sit down and go through why you did a certain thing a certain way because the code is not necessarily clearly explaining that or there's no documentation explaining that. Or if quite literally you have to tell a story about your code for it to make sense to other developers, you literally have folklore that is supporting your code. Now folklore is quite simply stories, right? This is stories that are passed on between people vocally, typically handed down. And so what you need to do is evaluate your projects, determine at what points has folklore entered your projects. When you have to say we're calling this, this object, let's say you have subscriptions in your application. This is something I dealt with actually today. If you have to say something like we're calling this a subscription, but really what it is is X, right? We're calling it a user, but really what it is is a computer. If you have to say these kinds of things, then there's evidence that your code needs to change. Your code needs to reflect the reality without telling a story. So catch yourself, go through the project that you're working on the next time that you are explaining something to another developer, find a way to capture how you are explaining it. If you can capture in your code what you are explaining, then your code becomes much more maintainable. This is kind of a heuristic, right? If you are trying to tell a story to explain why a given piece of code is the way that it is, try to tell that story in the code itself. If it's impossible for some reason, if there's something weird happening in an external API, for example, when you have to check what's going on in that API in order to be able to respond to it, then you need to document that weirdness. You need to document whatever that folklore is. It becomes, it's important that it is taken out of the conversational mode and put into a concrete mode and eventually work to get your code to the place where it describes if not all of the folklore, most if not all of the stories, the etymology of that code, so that you can look at the code and understand, oh, this isn't a subscription object. This is X. I hope this has been enlightening for you. Hopefully, as you are moving through new pieces of your code or looking at old code that you wrote or collaborating with other developers, you can identify when folklore has entered into the picture and identify how to eliminate it. Thank you so much for listening to today's episode of Developer Tea. Don't forget, Roebar is going to help you eliminate errors before your users see them. You can integrate Roebar into your existing workflow. You can send error alerts to Slack or HipChat and you can actually connect it to your source code directly. Tons of things you can do with Roebar. Remember, you can get the bootstrap plan for free just because you are a Developer Tealistener. Head over to Roebar.com slash Developer Tea. That's Roebar.com slash Developer Tea. And you can get the bootstrap plan for free. Thank you again to Roebar for sponsoring today's episode of Developer Tea. Thank you for listening to today's episode of Developer Tea. If you don't want to miss out on future episodes, make sure you subscribe and whatever podcasting app you use. You can reach out to me on Twitter at at Developer Tea. You can email me at Developer Tea. A Gmail.com. Hopefully you've heard all these things before. We would love to hear your feedback for Developer Tea. I need to hear from the audience that this show is made for. And you all are so good about getting in contact with me with questions. And I would love to hear more and more of this feedback. You can leave a review on iTunes, of course. And you can also always contact me once again at Developer Tea. A Gmail.com. Twitter at at Developer Tea. On Twitter at at Jakeatrel. Always love hearing from you all. Thank you so much for listening and until next time, enjoy your tea.