The Tone of Code
In today's episode, we talk about the "tone of code."
Relevant to today's episode:
One more thing...
Please take a moment and subscribe and review the show! Click here to review Developer Tea in iTunes.
Transcript (Generated by OpenAI Whisper)
Hey everyone and welcome to Developer Tea. My name is Jonathan Cutrell and in today's episode we're talking about the tone of code. In most cases the code we write is being written in concert with code that was either written by someone else or was written by us at a different point in time. In fact, that actually covers all cases. And the reason I point this out to you is to say that the code you are writing is going to be in an application usually that has code written by someone in a different context than you are currently in. Even from one day to the next, your mood or your tastes may change enough to affect the way you write code. Now hopefully as a good developer you are learning something new every day. A great developer is a perpetual student. So if you are truly learning every day then the code you wrote yesterday should be a little bit different from the code you will write today. Now of course this may sound a little bit exaggerated but if you take this concept and apply it to a larger scale project that is written across the span of say five years or maybe ten or fifteen people collaborating on it then it quickly becomes apparent that the code across the system could be quite different from one piece to the next especially with larger projects. So I titled this episode the tone of code because I want to inspire you to think of code in terms of metaphors. That's one of the things that I do pretty commonly on this show. And in today's episode we are using the metaphor of an orchestra. You see an orchestra has many different people playing many different instruments all in concert with one another and yet they have found a way to create music together and that is your job as the coder. In an orchestra the individual musicians are almost always reading from sheet music following a conductor's cues and playing off of each other to ensure that the notes the timing, the loudness, the timbre and every other detail contributes to the overall outcome of that performance. The individual musicians are paying very close attention to their tone. And in a team of developers it's your responsibility to act in a similar manner to pay attention to the tone of your code. No you don't have sheet music but maybe you have a style guide or a project plan and you don't have a conductor but you probably have a project lead of some sort. You are producing music together but you are certainly writing code and you're writing it in a particular style. You see when a project is executed like a well-rehearsed orchestra none of the code ends up feeling out of place. That doesn't mean that all of the code looks the same either because in an orchestra the different instruments come together to complement each other. You have instruments that are percussive and then you have instruments that are more on the base end of the scale and then you have instruments in the tenor scale and then the alto and the soprano. You have instruments in all of these things to come together and complement to have a fuller sound. But the important thing is to focus on writing code that isn't out of character with the rest of the applications code base. So where the different instruments in this particular metaphor might represent different types of code. For example a migration versus a view file versus a model versus a controller and maybe config files and style files and HTML or whatever the different types of things that you are writing. Obviously they are different from one another. They accomplish a different job from one another but they can all be in the same character. They can all have similar tone and accomplish a goal together. There are a lot of details about this that you can determine in your individual circumstances many of which are beyond the scope of today's episode but some examples may simply be following a code style guide. This is going to take care of a lot of the problems that you're going to have particularly within a single language. This may help you determine things like whether you're going to use camel casing or snake casing. It may help you determine where you put commas, where you put semicolons, very simple things but also it may help you determine your naming structures. It may help you determine how you organize your code. Code style guides can be incredibly helpful in the process of trying to bring your code into the same tone of the other code in the system. Another example is using what is already there rather than bringing in something new. In other words you shouldn't have two types of XML parsers brought into your application as two separate dependencies if you can help it. You shouldn't have one less file in a project that has everything else written in SAS or in stylus or in straight CSS. You shouldn't be using tools that are only for your portion of the code. You should be using the tools that are applicable for the rest of the code as well. If there's something very similar that accomplishes very similar goals then you should be using that thing rather than a second requirement. Now this kind of gets at why this is so important. The reason this is so important is because with other developers coming in, let's say you have a developer that comes in and they need to edit two or three different parts of the code and they realize that those two or three different parts of the code use two or three different similar tools like SAS and less or like two different XML parsers. Well now that particular developer has to learn two tools rather than one. They have to learn two coding styles rather than one and this becomes a big problem when you have multiple diversions spread out across a code base. Obviously as the code base grows, as it becomes older, there will be diversions in that code base but minimizing those diversions, matching the tone of the project is incredibly important because it becomes very difficult to maintain in the long run. That is the importance of this. Using the same structure or the file naming scheme, preferring similar methods for accomplishing similar goals. Even things as simple as matching the size of the average function or the class so that your code doesn't stick out or seem out of place. This is incredibly important. There's a common way of doing this. It's called looking at the shape of your code. If the shape of your code is very different from the shape of other pieces of code that are created for similar purposes in that code base, then maybe you have a little bit of a tone difference. These are the things to be aware of. Of course there are plenty more things that you can be aware of to shape the tone of your code to match the project. Ultimately, it's about collaborating with the other developers or really with yourself if you're the only person on the project, collaborating with the old code you wrote and the code that you're writing today. Don't get confused. This doesn't mean that the old code is good and that you have to follow it as the only standard. It could be that the tone of the old code actually needs to change. Maybe you have, indeed, learned something since you started the code base. Now it's time to start considering a refactor. Start considering a refactor so that you bring that tone into a better situation. This is like if the orchestra had not been practicing very much and finally they got everything together and things are coming together towards the end before they perform. Obviously refactoring code is going to be a big part of this process as well. So pay attention to the tone of the code you are writing and how it fits in in the project you are writing that code for. Thank you so much for listening to today's episode. I hope this episode was interesting to you, this idea of code having tone and how it fits together. Hopefully you have experienced this and if you haven't yet, you certainly will in the future. I'd love for you to reach out to me and let me know what kind of experiences you have. You can find me on Twitter at ad Developer Tea. You can send me an email at Developer Tea at gmail.com. And of course you can join this spec Slack channel by going to spec.fm slash slack. This is our Slack community there and it is free to you and you can come and talk to me directly on that Slack community as well as thousands of other talented designers and developers just like you who are in that community as well. Thank you so much for listening and until next time, enjoy your tea.